integrate encrypted kkt into nym-lp

enable encryption - kkt
Cleanup and fmt
2025-12-22 10:13:20 +01:00 · 2025-12-22 10:12:40 +01:00 · 2025-12-05 13:31:19 +01:00 · 2025-12-05 01:38:04 +01:00 · 2025-12-04 18:13:05 +01:00 · 2025-12-01 13:14:55 +01:00
246 changed files with 41837 additions and 7381 deletions
@@ -1,2 +1,5 @@
 nym-validator-rewarder/.sqlx/** diff=nodiff
 nym-node-status-api/nym-node-status-api/.sqlx/** diff=nodiff
+
+# Use bd merge for beads JSONL files
+.beads/beads.jsonl merge=beads
@@ -16,7 +16,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -10,13 +10,13 @@ env:

 jobs:
  check-if-tag-exists:
-    runs-on: arc-linux-latest-dind
+    runs-on: arc-ubuntu-22.04-dind
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -31,7 +31,7 @@ jobs:
          components: rustfmt, clippy

      - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v5
        with:
          go-version: "1.24.6"

@@ -14,6 +14,6 @@ jobs:
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@v6
+        uses: SonarSource/sonarqube-scan-action@v5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -34,7 +34,7 @@ jobs:
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './ppa'
@@ -8,6 +8,6 @@ jobs:
    steps:
    - uses: actions/first-interaction@v3
      with:
-        repo_token: ${{ secrets.GITHUB_TOKEN }}
-        issue_message: 'Thank you for raising this issue'
-        pr_message: 'Thank you for making this first PR'
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: 'Thank you for raising this issue'
+        pr-message: 'Thank you for making this first PR'
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-credential-proxy/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-network-monitor/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-api/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.48.1
+        uses: mikefarah/yq@v4.47.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -63,3 +63,6 @@ nym-api/redocly/formatted-openapi.json

 **/settings.sql
 **/enter_db.sh
+.beads
+CLAUDE.md
+docs
@@ -4,28 +4,6 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

-## [2025.21-mozzarella] (2025-11-25)
-
- [bugfix] Tunnel not waiting on MixnetClient to shut down cleanly ([#6225])
- bugfix: fix credential proxy upgrade mode attestation url arg ([#6202])
- HTTP API resilience enable & domain rotation conditions ([#6200])
- Remove debug feature from http-macro spec in gateway probe ([#6195])
- DNS relibility and troubleshooting  ([#6179])
- [bugfix] Distinguish authenticator errors by credential spent ([#6176])
- Typescript SDK 1.4.1 ([#6146])
- Enable URL rotation and retries for mixnet gateway init ([#6126])
- Feature/credential proxy jwt ([#5957])
-
-[#6225]: https://github.com/nymtech/nym/pull/6225
-[#6202]: https://github.com/nymtech/nym/pull/6202
-[#6200]: https://github.com/nymtech/nym/pull/6200
-[#6195]: https://github.com/nymtech/nym/pull/6195
-[#6179]: https://github.com/nymtech/nym/pull/6179
-[#6176]: https://github.com/nymtech/nym/pull/6176
-[#6146]: https://github.com/nymtech/nym/pull/6146
-[#6126]: https://github.com/nymtech/nym/pull/6126
-[#5957]: https://github.com/nymtech/nym/pull/5957
-
 ## [2025.20-leerdammer] (2025-11-12)

 - Max/tweak ts sdk actions ([#6185])
@@ -1,686 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Nym is a privacy platform that uses mixnet technology to protect against metadata surveillance. The platform consists of several key components:
- Mixnet nodes (mixnodes) for packet mixing
- Gateways (entry/exit points for the network)
- Clients for interacting with the network
- Network monitoring tools
- Validators for network consensus
- Various service providers and integrations
-
-## Build Commands
-
-### Rust Components
-
-```bash
-# Default build (debug)
-cargo build
-
-# Release build
-cargo build --release
-
-# Build a specific package
-cargo build -p <package-name>
-
-# Build main components
-make build
-
-# Build release versions of main binaries and contracts
-make build-release
-
-# Build specific binaries
-make build-nym-cli
-cargo build -p nym-node --release
-cargo build -p nym-api --release
-```
-
-### Testing
-
-```bash
-# Run clippy, unit tests, and formatting
-make test
-
-# Run all tests including slow tests
-make test-all
-
-# Run clippy on all workspaces
-make clippy
-
-# Run unit tests for a specific package
-cargo test -p <package-name>
-
-# Run only expensive/ignored tests
-cargo test --workspace -- --ignored
-
-# Run API tests
-dotenv -f envs/sandbox.env -- cargo test --test public-api-tests
-
-# Run tests with specific log level
-RUST_LOG=debug cargo test -p <package-name>
-
-# Run specific test scripts
-./nym-node/tests/test_apis.sh
-./scripts/wireguard-exit-policy/exit-policy-tests.sh
-```
-
-### Linting and Formatting
-
-```bash
-# Run rustfmt on all code
-make fmt
-
-# Check formatting without modifying
-cargo fmt --all -- --check
-
-# Run clippy with all targets
-cargo clippy --workspace --all-targets -- -D warnings
-
-# TypeScript linting
-yarn lint
-yarn lint:fix
-yarn types:lint:fix
-
-# Check dependencies for security/licensing issues
-cargo deny check
-```
-
-### WASM Components
-
-```bash
-# Build all WASM components
-make sdk-wasm-build
-
-# Build TypeScript SDK
-yarn build:sdk
-npx lerna run --scope @nymproject/sdk build --stream
-
-# Build and test WASM components
-make sdk-wasm
-
-# Build specific WASM packages
-cd wasm/client && make
-cd wasm/mix-fetch && make
-cd wasm/node-tester && make
-```
-
-### Contract Development
-
-```bash
-# Build all contracts
-make contracts
-
-# Build contracts in release mode
-make build-release-contracts
-
-# Generate contract schemas
-make contract-schema
-
-# Run wasm-opt on contracts
-make wasm-opt-contracts
-
-# Check contracts with cosmwasm-check
-make cosmwasm-check-contracts
-```
-
-### Running Components
-
-```bash
-# Run nym-node as a mixnode
-cargo run -p nym-node -- run --mode mixnode
-
-# Run nym-node as a gateway
-cargo run -p nym-node -- run --mode gateway
-
-# Run the network monitor
-cargo run -p nym-network-monitor
-
-# Run the API server
-cargo run -p nym-api
-
-# Run with specific environment
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Start a local network
-./scripts/localnet_start.sh
-```
-
-## Architecture
-
-The Nym platform consists of various components organized as a monorepo:
-
-1. **Core Mixnet Infrastructure**:
-   - `nym-node`: Core binary supporting mixnode and gateway modes
-   - `common/nymsphinx`: Implementation of the Sphinx packet format
-   - `common/topology`: Network topology management
-   - `common/types`: Shared data types across components
-
-2. **Network Monitoring**:
-   - `nym-network-monitor`: Monitors the network's reliability and performance
-   - `nym-api`: API server for network stats and monitoring data
-   - Metrics tracking for nodes, routes, and overall network health
-
-3. **Client Implementations**:
-   - `clients/native`: Native Rust client implementation
-   - `clients/socks5`: SOCKS5 proxy client for standard applications
-   - `wasm`: WebAssembly client implementations (for browsers)
-   - `nym-connect`: Desktop and mobile clients
-
-4. **Blockchain & Smart Contracts**:
-   - `common/cosmwasm-smart-contracts`: Smart contract implementations
-   - `contracts`: CosmWasm contracts for the Nym network
-   - `common/ledger`: Blockchain integration
-
-5. **Utilities & Tools**:
-   - `tools`: Various CLI tools and utilities
-   - `sdk`: SDKs for different languages and platforms
-   - `documentation`: Documentation generation and management
-
-## Packet System
-
-Nym uses a modified Sphinx packet format for its mixnet:
-
-1. **Message Chunking**:
-   - Messages are divided into "sets" and "fragments"
-   - Each fragment fits in a single Sphinx packet
-   - The `common/nymsphinx/chunking` module handles message fragmentation
-
-2. **Routing**:
-   - Packets traverse through 3 layers of mixnodes
-   - Routing information is encrypted in layers (onion routing)
-   - The final gateway receives and processes the messages
-
-3. **Monitoring**:
-   - Monitoring system tracks packet delivery through the network
-   - Routes are analyzed for reliability statistics
-   - Node performance metrics are collected
-
-## Network Protocol
-
-Nym implements the Loopix mixnet design with several key privacy features:
-
-1. **Continuous-time Mixing**:
-   - Each mixnode delays messages independently with an exponential distribution
-   - This creates random reordering of packets, destroying timing correlations
-   - Offers better anonymity properties than batch mixing approaches
-
-2. **Cover Traffic**:
-   - Clients and nodes generate dummy "loop" packets that circulate through the network
-   - These packets are indistinguishable from real traffic
-   - Creates a baseline level of traffic that hides actual communication patterns
-   - Provides unobservability (hiding when and how much real traffic is being sent)
-
-3. **Stratified Network Architecture**:
-   - Traffic flows through Entry Gateway → 3 Mixnode Layers → Exit Gateway
-   - Path selection is independent per-message (unlike Tor)
-   - Each node connects only to adjacent layers
-
-4. **Anonymous Replies**:
-   - Single-Use Reply Blocks (SURBs) allow receiving messages without revealing identity
-   - Enables bidirectional communication while maintaining privacy
-
-## Network Monitoring Architecture
-
-The network monitoring system is a core component that measures mixnet reliability:
-
-1. The `nym-network-monitor` sends test packets through the network
-2. These packets follow predefined routes through multiple mixnodes
-3. Metrics are collected about:
-   - Successful and failed packet deliveries
-   - Node reliability (percentage of successful packet handling)
-   - Route reliability (which specific route combinations work best)
-4. Results are stored in the database and used by `nym-api` to:
-   - Present node performance statistics
-   - Determine network rewards
-   - Provide route selection guidance to clients
-
-In the current branch, metrics collection is being enhanced with a fanout approach to submit to multiple API endpoints.
-
-## Development Environment
-
-### Required Dependencies
-
- Rust toolchain (stable, 1.80+)
- Node.js (v20+) and yarn for TypeScript components
- SQLite for local database development
- PostgreSQL for API database (optional, for full API functionality)
- CosmWasm tools for contract development
- For building contracts: `wasm-opt` tool from `binaryen`
- Python 3.8+ for some scripts
- Docker (optional, for containerized development)
- protoc (Protocol Buffers compiler) for some components
-
-### Environment Configurations
-
-The `envs/` directory contains pre-configured environments:
-
-#### Available Environments
-
- **`local.env`**: Local development environment
-  - Points to local services (localhost)
-  - Uses test mnemonics and keys
-  - Ideal for testing without external dependencies
-
- **`sandbox.env`**: Sandbox test network
-  - Public test network with real nodes
-  - Test tokens available from faucet
-  - Contract addresses for sandbox deployment
-  - API: https://sandbox-nym-api1.nymtech.net
-
- **`mainnet.env`**: Production mainnet
-  - Real network with real tokens
-  - Production contract addresses
-  - API: https://validator.nymtech.net
-  - Use with caution!
-
- **`canary.env`**: Canary deployment
-  - Pre-release testing environment
-  - Tests new features before mainnet
-
- **`mainnet-local-api.env`**: Hybrid environment
-  - Uses mainnet contracts but local API
-  - Useful for API development against mainnet data
-
-#### Key Environment Variables
-
-```bash
-# Network configuration
-NETWORK_NAME=sandbox              # Network identifier
-BECH32_PREFIX=n                   # Address prefix (n for sandbox, n for mainnet)
-NYM_API=https://sandbox-nym-api1.nymtech.net/api
-NYXD=https://rpc.sandbox.nymtech.net
-NYM_API_NETWORK=sandbox
-
-# Contract addresses (network-specific)
-MIXNET_CONTRACT_ADDRESS=n1xr3rq8yvd7qplsw5yx90ftsr2zdhg4e9z60h5duusgxpv72hud3sjkxkav
-VESTING_CONTRACT_ADDRESS=n1unyuj8qnmygvzuex3dwmg9yzt9alhvyeat0uu0jedg2wj33efl5qackslz
-# ... other contract addresses
-
-# Mnemonic for testing (NEVER use in production)
-MNEMONIC="clutch captain shoe salt awake harvest setup primary inmate ugly among become"
-
-# API Keys and tokens
-IPINFO_API_TOKEN=your_token_here
-AUTHENTICATOR_PASSWORD=password_here
-
-# Logging
-RUST_LOG=info                    # Options: error, warn, info, debug, trace
-RUST_BACKTRACE=1                # Enable backtraces
-
-# Database
-DATABASE_URL=postgresql://user:pass@localhost/nym_api
-```
-
-#### Using Environment Files
-
-```bash
-# Load environment and run command
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Export to shell
-source envs/sandbox.env
-
-# Use with make targets
-dotenv -f envs/sandbox.env -- make run-api-tests
-```
-
-## Initial Setup
-
-### First Time Setup
-
-1. **Install Prerequisites**
-   ```bash
-   # Install Rust
-   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-   
-   # Install Node.js and yarn
-   # Via nvm (recommended):
-   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-   nvm install 20
-   npm install -g yarn
-   
-   # Install build tools
-   # Ubuntu/Debian:
-   sudo apt-get install build-essential pkg-config libssl-dev protobuf-compiler libpq-dev
-   
-   # macOS:
-   brew install protobuf postgresql
-   
-   # Install wasm-opt for contract builds
-   npm install -g wasm-opt
-   
-   # Add wasm target for Rust
-   rustup target add wasm32-unknown-unknown
-   ```
-
-2. **Clone and Setup Repository**
-   ```bash
-   git clone https://github.com/nymtech/nym.git
-   cd nym/nym
-   
-   # Install JavaScript dependencies
-   yarn install
-   
-   # Build the project
-   make build
-   ```
-
-3. **Database Setup (Optional, for API development)**
-   ```bash
-   # Install PostgreSQL
-   # Create database
-   createdb nym_api
-   
-   # Run migrations (from nym-api directory)
-   cd nym-api
-   sqlx migrate run
-   ```
-
-### Quick Start
-
-```bash
-# Run a mixnode locally
-dotenv -f envs/sandbox.env -- cargo run -p nym-node -- run --mode mixnode --id my-mixnode
-
-# Run a gateway locally
-dotenv -f envs/sandbox.env -- cargo run -p nym-node -- run --mode gateway --id my-gateway
-
-# Run the API server
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Run a client
-cargo run -p nym-client -- init --id my-client
-cargo run -p nym-client -- run --id my-client
-```
-
-## CI/CD Pipeline
-
-The project uses GitHub Actions for CI/CD with several key workflows:
-
-1. **Build and Test**:
-   - `ci-build.yml`: Main build workflow for Rust components
-   - Tests are run on multiple platforms (Linux, Windows, macOS)
-   - Includes formatting check (rustfmt) and linting (clippy)
-
-2. **Release Process**:
-   - Binary artifacts are published on release tags
-   - Multiple platform builds are created
-
-3. **Documentation**:
-   - Documentation is automatically built and deployed
-
-## Database Structure
-
-The system uses SQLite databases with tables like:
- `mixnode_status`: Status information about mixnodes
- `gateway_status`: Status information about gateways
- `routes`: Route performance information (success/failure of specific paths)
- `monitor_run`: Information about monitoring test runs
-
-## Development Workflows
-
-### Running a Node
-
-To run the mixnode or gateway:
-
-```bash
-# Run nym-node as a mixnode with specified identity
-cargo run -p nym-node -- run --mode mixnode --id my-mixnode
-
-# Run nym-node as a gateway
-cargo run -p nym-node -- run --mode gateway --id my-gateway
-```
-
-### Configuration
-
-Nodes can be configured with files in various locations:
- Command-line arguments
- Environment variables
- `.env` files specified with `--config-env-file`
-
-### Monitoring
-
-To monitor the health of your node:
- View logs for real-time information
- Use the node's HTTP API for status information
- Check the explorer for public node statistics
-
-## Common Libraries
-
- `common/types`: Shared data types across all components
- `common/crypto`: Cryptographic primitives and wrappers
- `common/client-core`: Core client functionality
- `common/gateway-client`: Client-gateway communication
- `common/task`: Task management and concurrency utilities
- `common/nymsphinx`: Sphinx packet implementation for mixnet
- `common/topology`: Network topology management
- `common/credentials`: Credential system for privacy-preserving authentication
- `common/bandwidth-controller`: Bandwidth management and accounting
-
-## Code Conventions
-
- Error handling: Use anyhow/thiserror for structured error handling
- Logging: Use the tracing framework for logging and diagnostics
- State management: Generally use Tokio/futures for async code
- Configuration: Use the config crate and env vars with defaults
- Database: Use sqlx for type-safe database queries
- Follow clippy recommendations and rustfmt formatting
- Use semantic commit messages: feat, fix, docs, refactor, test, chore
-
-## When Making Changes
-
- Run `make test` before submitting PRs
- Follow Rust naming conventions
- Use `clippy` to check for common issues
- Update SQLx query caches when modifying DB queries: `cargo sqlx prepare`
- Consider backward compatibility for protocol changes
- Use lefthook pre-commit hooks for TypeScript formatting
- Run `cargo deny check` to verify dependency compliance
- Test against both sandbox and local environments when possible
- Update relevant documentation and CHANGELOG.md
-
-## Development Tools
-
-### Useful Cargo Commands
-
-```bash
-# Check for outdated dependencies
-cargo outdated
-
-# Analyze binary size
-cargo bloat --release -p nym-node
-
-# Generate dependency graph
-cargo tree -p nym-api
-
-# Run with instrumentation
-cargo run --features profiling -p nym-node
-
-# Check for security advisories
-cargo audit
-```
-
-### Database Tools
-
-```bash
-# SQLx CLI for migrations
-cargo install sqlx-cli
-
-# Create new migration
-cd nym-api && sqlx migrate add <migration_name>
-
-# Prepare query metadata for offline compilation
-cargo sqlx prepare --workspace
-
-# View database schema
-./nym-api/enter_db.sh
-```
-
-### Development Scripts
-
- `scripts/build_topology.py`: Generate network topology files
- `scripts/node_api_check.py`: Verify node API endpoints
- `scripts/network_tunnel_manager.sh`: Manage network tunnels
- `scripts/localnet_start.sh`: Start a local test network
- Various deployment scripts in `deployment/` for different environments
-
-## Debugging
-
- Enable more verbose logging with the RUST_LOG environment variable:
-  ```
-  RUST_LOG=debug,nym_node=trace cargo run -p nym-node -- run --mode mixnode
-  ```
- Use the HTTP API endpoints for status information
- Check monitoring data in the database for network performance metrics
- For complex issues, use tracing tools to follow packet flow
- Enable backtraces: `RUST_BACKTRACE=full`
- For WASM debugging: Use browser developer tools with source maps
-
-## Deployment and Advanced Configurations
-
-### Deployment Structure
-
-The `deployment/` directory contains Ansible playbooks and configurations for various deployment scenarios:
-
- **`aws/`**: AWS-specific deployment configurations
- **`mixnode/`**: Mixnode deployment playbooks
- **`gateway/`**: Gateway deployment playbooks
- **`validator/`**: Validator node deployment
- **`sandbox-v2/`**: Complete sandbox environment setup
- **`big-dipper-2/`**: Block explorer deployment
-
-### Sandbox V2 Deployment
-
-The sandbox-v2 deployment (`deployment/sandbox-v2/`) provides a complete test environment:
-
-```bash
-# Key playbooks:
- deploy.yaml              # Main deployment orchestrator
- deploy-mixnodes.yaml    # Deploy mixnodes
- deploy-gateways.yaml    # Deploy gateways
- deploy-validators.yaml  # Deploy validator nodes
- deploy-nym-api.yaml     # Deploy API services
-```
-
-### Custom Environment Setup
-
-To create a custom environment:
-
-1. Copy an existing env file: `cp envs/sandbox.env envs/custom.env`
-2. Modify the network endpoints and contract addresses
-3. Update the `NETWORK_NAME` to your identifier
-4. Set appropriate mnemonics and keys (use fresh ones for production!)
-
-### Contract Addresses
-
-Contract addresses are network-specific and defined in environment files:
- Mixnet contract: Manages mixnode/gateway registry
- Vesting contract: Handles token vesting schedules
- Coconut contracts: Privacy-preserving credentials
- Name service: Human-readable address mapping
- Ecash contract: Electronic cash functionality
-
-### Local Network Setup
-
-For a completely local network:
-```bash
-# Start local chain
-./scripts/localnet_start.sh
-
-# Deploy contracts
-cd contracts
-make deploy-local
-
-# Start nodes with local config
-dotenv -f envs/local.env -- cargo run -p nym-node -- run --mode mixnode
-```
-
-## Common Issues and Troubleshooting
-
-### Database Issues
-
- When modifying database queries, you must update SQLx query caches:
-  ```bash
-  cargo sqlx prepare
-  ```
- If you see SQLx errors about missing query files, this is likely the cause
- For "database is locked" errors with SQLite, ensure only one process accesses the DB
- For PostgreSQL connection issues, verify DATABASE_URL and that the server is running
-
-### API Connection Issues
-
- Check the environment variables pointing to the APIs (NYM_API, NYXD)
- Verify network connectivity and API health endpoints
- For authentication issues, check node keys and credentials
- Common endpoints to verify:
-  - API health: `$NYM_API/health`
-  - Chain status: `$NYXD/status`
-  - Contract info: `$NYXD/cosmwasm/wasm/v1/contract/$CONTRACT_ADDRESS`
-
-### Build Problems
-
- Clean dependencies with `cargo clean` for a fresh build
- Check for compatible Rust version (1.80+ recommended)
- For smart contract builds, ensure wasm-opt is installed: `npm install -g wasm-opt`
- For cross-compilation issues, check target-specific dependencies
- WASM build issues: Ensure wasm32-unknown-unknown target is installed:
-  ```bash
-  rustup target add wasm32-unknown-unknown
-  ```
- For "cannot find -lpq" errors, install PostgreSQL development files:
-  ```bash
-  # Ubuntu/Debian
-  sudo apt-get install libpq-dev
-  # macOS
-  brew install postgresql
-  ```
-
-### Environment Issues
-
- Contract address mismatches: Ensure you're using the correct environment file
- "Account sequence mismatch": The account nonce is out of sync, wait and retry
- Token decimal issues: Sandbox uses different decimal places than mainnet
- API version mismatches: Ensure your local API version matches the network
- "Insufficient funds": Get test tokens from faucet (sandbox) or check balance
- Gateway/mixnode bonding issues: Verify minimum stake requirements
-
-## Working with Routes and Monitoring
-
-1. Route monitoring metrics are stored in a `routes` table with:
-   - Layer node IDs (layer1, layer2, layer3, gw)
-   - Success flag (boolean)
-   - Timestamp
-
-2. To analyze routes:
-   - Check `NetworkAccount` and `AccountingRoute` in `nym-network-monitor/src/accounting.rs`
-   - View monitoring logic in `common/nymsphinx/chunking/monitoring.rs`
-   - Observe how routes are submitted to the database in the `submit_accounting_routes_to_db` function
-
-## Performance Optimization
-
-### Profiling and Benchmarking
-
-```bash
-# Run benchmarks
-cargo bench -p nym-node
-
-# Profile with perf (Linux)
-cargo build --release --features profiling
-perf record --call-graph=dwarf ./target/release/nym-node run --mode mixnode
-perf report
-
-# Generate flamegraph
-cargo install flamegraph
-cargo flamegraph --bin nym-node -- run --mode mixnode
-```
-
-### Common Performance Considerations
-
- Use bounded channels for backpressure
- Batch database operations where possible
- Monitor memory usage with `RUST_LOG=nym_node::metrics=debug`
- Use connection pooling for database connections
- Consider using `jemalloc` for better memory allocation performance
@@ -165,6 +165,15 @@ version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"

+[[package]]
+name = "ansi_term"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d52a9bb7ec0cf484c551830a7ce27bd20d67eac647e1befb56b0be4ee39a55d2"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "anstream"
 version = "0.6.19"
@@ -991,6 +1000,12 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7"

+[[package]]
+name = "byte_string"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11aade7a05aa8c3a351cedc44c3fc45806430543382fcc4743a9b757a2a0b4ed"
+
 [[package]]
 name = "bytecodec"
 version = "0.4.15"
@@ -1259,6 +1274,16 @@ version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b94f61472cee1439c0b966b47e3aca9ae07e45d070759512cd390ea2bebc6675"

+[[package]]
+name = "classic-mceliece-rust"
+version = "3.2.0"
+source = "git+https://github.com/georgio/classic-mceliece-rust#f2f27048b621df103bbe64369a18174ffec04ae1"
+dependencies = [
+ "rand 0.9.2",
+ "sha3",
+ "zeroize",
+]
+
 [[package]]
 name = "coarsetime"
 version = "0.1.36"
@@ -1283,7 +1308,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "117725a109d387c937a1533ce01b450cbde6b88abceea8473c4d7a85853cda3c"
 dependencies = [
 "lazy_static",
- "windows-sys 0.48.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -1432,6 +1457,16 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"

+[[package]]
+name = "core-models"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "pastey",
+ "rand 0.9.2",
+]
+
 [[package]]
 name = "cosmos-sdk-proto"
 version = "0.26.1"
@@ -1859,6 +1894,7 @@ dependencies = [
 "curve25519-dalek-derive",
 "digest 0.10.7",
 "fiat-crypto",
+ "rand_core 0.6.4",
 "rustc_version 0.4.1",
 "serde",
 "subtle 2.6.1",
@@ -3159,6 +3195,43 @@ dependencies = [
 "hashbrown 0.15.4",
 ]

+[[package]]
+name = "hax-lib"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74d9ba66d1739c68e0219b2b2238b5c4145f491ebf181b9c6ab561a19352ae86"
+dependencies = [
+ "hax-lib-macros",
+ "num-bigint",
+ "num-traits",
+]
+
+[[package]]
+name = "hax-lib-macros"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24ba777a231a58d1bce1d68313fa6b6afcc7966adef23d60f45b8a2b9b688bf1"
+dependencies = [
+ "hax-lib-macros-types",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
+[[package]]
+name = "hax-lib-macros-types"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "867e19177d7425140b417cd27c2e05320e727ee682e98368f88b7194e80ad515"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "serde_json",
+ "uuid",
+]
+
 [[package]]
 name = "hdrhistogram"
 version = "7.5.4"
@@ -3965,7 +4038,7 @@ checksum = "e04d7f318608d35d4b61ddd75cbdaee86b023ebe2bd5a66ee0915f0bf93095a9"
 dependencies = [
 "hermit-abi",
 "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -4107,6 +4180,15 @@ dependencies = [
 "signature",
 ]

+[[package]]
+name = "keccak"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecc2af9a1119c51f12a14607e783cb977bde58bc069ff0c3da1095e635d70654"
+dependencies = [
+ "cpufeatures",
+]
+
 [[package]]
 name = "keystream"
 version = "1.0.0"
@@ -4185,6 +4267,213 @@ version = "0.2.174"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1171693293099992e19cddea4e8b849964e9846f4acee11b3948bcc337be8776"

+[[package]]
+name = "libcrux-chacha20poly1305"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-poly1305",
+ "libcrux-secrets",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-curve25519"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-secrets",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-ecdh"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-curve25519",
+ "libcrux-p256",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-ed25519"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-sha2",
+ "rand_core 0.9.3",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-hacl-rs"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-macros",
+]
+
+[[package]]
+name = "libcrux-hkdf"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-hmac",
+ "libcrux-secrets",
+]
+
+[[package]]
+name = "libcrux-hmac"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-sha2",
+]
+
+[[package]]
+name = "libcrux-intrinsics"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "core-models",
+ "hax-lib",
+]
+
+[[package]]
+name = "libcrux-kem"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-curve25519",
+ "libcrux-ecdh",
+ "libcrux-ml-kem",
+ "libcrux-p256",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-macros"
+version = "0.0.3"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "quote",
+ "syn 2.0.106",
+]
+
+[[package]]
+name = "libcrux-ml-kem"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "libcrux-intrinsics",
+ "libcrux-platform",
+ "libcrux-secrets",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-p256"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-secrets",
+ "libcrux-sha2",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-platform"
+version = "0.0.2"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "libcrux-poly1305"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+]
+
+[[package]]
+name = "libcrux-psq"
+version = "0.0.5"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-chacha20poly1305",
+ "libcrux-ecdh",
+ "libcrux-ed25519",
+ "libcrux-hkdf",
+ "libcrux-hmac",
+ "libcrux-kem",
+ "libcrux-ml-kem",
+ "libcrux-sha2",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-secrets"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+]
+
+[[package]]
+name = "libcrux-sha2"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-sha3"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "libcrux-intrinsics",
+ "libcrux-platform",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-traits"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-secrets",
+ "rand 0.9.2",
+]
+
 [[package]]
 name = "libm"
 version = "0.2.15"
@@ -4374,11 +4663,11 @@ dependencies = [

 [[package]]
 name = "matchers"
-version = "0.2.0"
+version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
+checksum = "8263075bb86c5a1b1427b5ae862e8889656f126e9f77c484496e8b47cf5c5558"
 dependencies = [
- "regex-automata",
+ "regex-automata 0.1.10",
 ]

 [[package]]
@@ -4741,15 +5030,6 @@ dependencies = [
 "winapi",
 ]

-[[package]]
-name = "nu-ansi-term"
-version = "0.50.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4a28e057d01f97e61255210fcff094d74ed0466038633e95017f5beb68e4399"
-dependencies = [
- "windows-sys 0.52.0",
-]
-
 [[package]]
 name = "num-bigint"
 version = "0.4.6"
@@ -4823,6 +5103,28 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "num_enum"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1207a7e20ad57b847bbddc6776b968420d38292bbfe2089accff5e19e82454c"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff32365de1b6743cb203b710788263c44a03de03802daf96092f2da4fe6ba4d7"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
 [[package]]
 name = "num_threads"
 version = "0.1.7"
@@ -4834,7 +5136,7 @@ dependencies = [

 [[package]]
 name = "nym-api"
-version = "1.1.71"
+version = "1.1.69"
 dependencies = [
 "anyhow",
 "async-trait",
@@ -4905,7 +5207,7 @@ dependencies = [
 "tokio",
 "tokio-stream",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "ts-rs",
 "url",
@@ -5057,7 +5359,7 @@ dependencies = [

 [[package]]
 name = "nym-cli"
-version = "1.1.68"
+version = "1.1.66"
 dependencies = [
 "anyhow",
 "base64 0.22.1",
@@ -5140,7 +5442,7 @@ dependencies = [

 [[package]]
 name = "nym-client"
-version = "1.1.68"
+version = "1.1.66"
 dependencies = [
 "bs58",
 "clap",
@@ -5487,7 +5789,7 @@ dependencies = [
 "time",
 "tokio",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "url",
 "utoipa",
@@ -5616,6 +5918,7 @@ dependencies = [
 "nym-ecash-contract-common",
 "nym-gateway-requests",
 "nym-gateway-storage",
+ "nym-metrics",
 "nym-task",
 "nym-upgrade-mode-check",
 "nym-validator-client",
@@ -5681,6 +5984,7 @@ dependencies = [
 "bs58",
 "cipher",
 "ctr",
+ "curve25519-dalek",
 "digest 0.10.7",
 "ed25519-dalek",
 "generic-array 0.14.7",
@@ -5813,6 +6117,7 @@ dependencies = [
 "bincode",
 "bip39",
 "bs58",
+ "bytes",
 "dashmap",
 "defguard_wireguard_rs",
 "fastrand 2.3.0",
@@ -5830,10 +6135,14 @@ dependencies = [
 "nym-gateway-storage",
 "nym-id",
 "nym-ip-packet-router",
+ "nym-kcp",
+ "nym-lp",
+ "nym-metrics",
 "nym-mixnet-client",
 "nym-network-defaults",
 "nym-network-requester",
 "nym-node-metrics",
+ "nym-registration-common",
 "nym-sdk",
 "nym-service-provider-requests-common",
 "nym-sphinx",
@@ -5907,6 +6216,7 @@ dependencies = [
 "clap",
 "futures",
 "hex",
+ "nym-api-requests",
 "nym-authenticator-client",
 "nym-authenticator-requests",
 "nym-bandwidth-controller",
@@ -5922,7 +6232,13 @@ dependencies = [
 "nym-http-api-client-macro",
 "nym-ip-packet-client",
 "nym-ip-packet-requests",
+ "nym-lp",
+ "nym-mixnet-contract-common",
+ "nym-network-defaults",
+ "nym-node-requests",
 "nym-node-status-client",
+ "nym-registration-client",
+ "nym-registration-common",
 "nym-sdk",
 "nym-topology",
 "nym-validator-client",
@@ -5931,6 +6247,7 @@ dependencies = [
 "serde",
 "serde_json",
 "thiserror 2.0.12",
+ "time",
 "tokio",
 "tokio-util",
 "tracing",
@@ -6213,6 +6530,48 @@ dependencies = [
 "url",
 ]

+[[package]]
+name = "nym-kcp"
+version = "0.1.0"
+dependencies = [
+ "ansi_term",
+ "byte_string",
+ "bytes",
+ "env_logger",
+ "log",
+ "thiserror 2.0.12",
+ "tokio-util",
+]
+
+[[package]]
+name = "nym-kkt"
+version = "0.1.0"
+dependencies = [
+ "aead",
+ "arc-swap",
+ "blake3",
+ "bytes",
+ "classic-mceliece-rust",
+ "criterion",
+ "curve25519-dalek",
+ "futures",
+ "libcrux-ecdh",
+ "libcrux-kem",
+ "libcrux-ml-kem",
+ "libcrux-psq",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "nym-crypto",
+ "pin-project",
+ "rand 0.9.2",
+ "strum",
+ "thiserror 2.0.12",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "zeroize",
+]
+
 [[package]]
 name = "nym-ledger"
 version = "0.1.0"
@@ -6224,6 +6583,43 @@ dependencies = [
 "thiserror 2.0.12",
 ]

+[[package]]
+name = "nym-lp"
+version = "0.1.0"
+dependencies = [
+ "ansi_term",
+ "bincode",
+ "bs58",
+ "bytes",
+ "chacha20poly1305",
+ "criterion",
+ "dashmap",
+ "libcrux-kem",
+ "libcrux-psq",
+ "libcrux-traits",
+ "num_enum",
+ "nym-crypto",
+ "nym-kkt",
+ "nym-lp-common",
+ "nym-sphinx",
+ "parking_lot",
+ "rand 0.8.5",
+ "rand 0.9.2",
+ "rand_chacha 0.3.1",
+ "serde",
+ "sha2 0.10.9",
+ "snow",
+ "thiserror 2.0.12",
+ "tls_codec",
+ "tracing",
+ "utoipa",
+ "zeroize",
+]
+
+[[package]]
+name = "nym-lp-common"
+version = "0.1.0"
+
 [[package]]
 name = "nym-metrics"
 version = "0.1.0"
@@ -6367,7 +6763,7 @@ dependencies = [

 [[package]]
 name = "nym-network-requester"
-version = "1.1.69"
+version = "1.1.67"
 dependencies = [
 "addr",
 "anyhow",
@@ -6417,7 +6813,7 @@ dependencies = [

 [[package]]
 name = "nym-node"
-version = "1.23.0"
+version = "1.21.0"
 dependencies = [
 "anyhow",
 "arc-swap",
@@ -6491,7 +6887,7 @@ dependencies = [
 "tokio-stream",
 "tokio-util",
 "toml 0.8.23",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "tracing-indicatif",
 "tracing-subscriber",
@@ -6561,7 +6957,7 @@ dependencies = [

 [[package]]
 name = "nym-node-status-api"
-version = "4.0.12"
+version = "4.0.11-rc1"
 dependencies = [
 "ammonia",
 "anyhow",
@@ -6609,7 +7005,7 @@ dependencies = [
 "tokio",
 "tokio-stream",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "tracing-log 0.2.0",
 "tracing-subscriber",
@@ -6800,15 +7196,21 @@ dependencies = [
 name = "nym-registration-client"
 version = "0.1.0"
 dependencies = [
+ "bincode",
+ "bytes",
 "futures",
 "nym-authenticator-client",
 "nym-bandwidth-controller",
 "nym-credential-storage",
 "nym-credentials-interface",
+ "nym-crypto",
 "nym-ip-packet-client",
+ "nym-lp",
 "nym-registration-common",
 "nym-sdk",
 "nym-validator-client",
+ "nym-wireguard-types",
+ "rand 0.8.5",
 "thiserror 2.0.12",
 "tokio",
 "tokio-util",
@@ -6821,10 +7223,15 @@ dependencies = [
 name = "nym-registration-common"
 version = "0.1.0"
 dependencies = [
+ "bincode",
 "nym-authenticator-requests",
+ "nym-credentials-interface",
 "nym-crypto",
 "nym-ip-packet-requests",
 "nym-sphinx",
+ "nym-wireguard-types",
+ "serde",
+ "time",
 "tokio-util",
 ]

@@ -6946,7 +7353,7 @@ dependencies = [

 [[package]]
 name = "nym-socks5-client"
-version = "1.1.68"
+version = "1.1.66"
 dependencies = [
 "bs58",
 "clap",
@@ -7206,7 +7613,7 @@ dependencies = [

 [[package]]
 name = "nym-statistics-api"
-version = "0.3.0"
+version = "0.2.1"
 dependencies = [
 "anyhow",
 "axum",
@@ -7220,12 +7627,13 @@ dependencies = [
 "nym-statistics-common",
 "nym-task",
 "nym-validator-client",
+ "serde",
 "serde_json",
 "sqlx",
 "time",
 "tokio",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "tracing-subscriber",
 "url",
@@ -7406,7 +7814,6 @@ dependencies = [
 name = "nym-validator-client"
 version = "0.1.0"
 dependencies = [
- "anyhow",
 "async-trait",
 "base64 0.22.1",
 "bip32",
@@ -7584,15 +7991,20 @@ dependencies = [
 "defguard_wireguard_rs",
 "futures",
 "ip_network",
+ "ipnetwork",
+ "log",
 "nym-credential-verification",
 "nym-credentials-interface",
 "nym-crypto",
 "nym-gateway-requests",
 "nym-gateway-storage",
+ "nym-ip-packet-requests",
+ "nym-metrics",
 "nym-network-defaults",
 "nym-node-metrics",
 "nym-task",
 "nym-wireguard-types",
+ "rand 0.8.5",
 "thiserror 2.0.12",
 "tokio",
 "tokio-stream",
@@ -7624,7 +8036,7 @@ dependencies = [
 "nym-wireguard-private-metadata-shared",
 "tokio",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "utoipa",
 "utoipa-swagger-ui",
 ]
@@ -7662,7 +8074,7 @@ dependencies = [
 "time",
 "tokio",
 "tower 0.5.2",
- "tower-http",
+ "tower-http 0.5.2",
 "utoipa",
 ]

@@ -7680,7 +8092,7 @@ dependencies = [

 [[package]]
 name = "nymvisor"
-version = "0.1.33"
+version = "0.1.31"
 dependencies = [
 "anyhow",
 "bytes",
@@ -7731,7 +8143,7 @@ dependencies = [
 "time",
 "tokio",
 "tokio-util",
- "tower-http",
+ "tower-http 0.5.2",
 "tracing",
 "tracing-subscriber",
 "utoipa",
@@ -8034,6 +8446,12 @@ version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"

+[[package]]
+name = "pastey"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
+
 [[package]]
 name = "peg"
 version = "0.8.5"
@@ -8659,7 +9077,7 @@ dependencies = [
 "once_cell",
 "socket2 0.5.10",
 "tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -8820,8 +9238,17 @@ checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
 dependencies = [
 "aho-corasick",
 "memchr",
- "regex-automata",
- "regex-syntax",
+ "regex-automata 0.4.9",
+ "regex-syntax 0.8.5",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c230d73fb8d8c1b9c0b3135c5142a8acee3a0558fb8db5cf1cb65f8d7862132"
+dependencies = [
+ "regex-syntax 0.6.29",
 ]

 [[package]]
@@ -8832,9 +9259,15 @@ checksum = "809e8dc61f6de73b46c85f4c96486310fe304c434cfa43669d7b40f711150908"
 dependencies = [
 "aho-corasick",
 "memchr",
- "regex-syntax",
+ "regex-syntax 0.8.5",
 ]

+[[package]]
+name = "regex-syntax"
+version = "0.6.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f162c6dd7b008981e4d40210aca20b4bd0f9b60ca9271061b07f78537722f2e1"
+
 [[package]]
 name = "regex-syntax"
 version = "0.8.5"
@@ -8914,7 +9347,7 @@ dependencies = [
 "tokio-rustls 0.26.2",
 "tokio-util",
 "tower 0.5.2",
- "tower-http",
+ "tower-http 0.6.6",
 "tower-service",
 "url",
 "wasm-bindgen",
@@ -9114,7 +9547,7 @@ dependencies = [
 "errno",
 "libc",
 "linux-raw-sys 0.4.15",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -9764,6 +10197,16 @@ dependencies = [
 "digest 0.10.7",
 ]

+[[package]]
+name = "sha3"
+version = "0.10.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75872d278a8f37ef87fa0ddbda7802605cb18344497949862c0d4dcb291eba60"
+dependencies = [
+ "digest 0.10.7",
+ "keccak",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -10430,7 +10873,7 @@ dependencies = [
 "getrandom 0.3.3",
 "once_cell",
 "rustix 1.0.8",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -10750,6 +11193,27 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"

+[[package]]
+name = "tls_codec"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de2e01245e2bb89d6f05801c564fa27624dbd7b1846859876c7dad82e90bf6b"
+dependencies = [
+ "tls_codec_derive",
+ "zeroize",
+]
+
+[[package]]
+name = "tls_codec_derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d2e76690929402faae40aebdda620a2c0e25dd6d3b9afe48867dfd95991f4bd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
 [[package]]
 name = "tokio"
 version = "1.47.1"
@@ -11049,9 +11513,9 @@ dependencies = [

 [[package]]
 name = "tower-http"
-version = "0.6.6"
+version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "adc82fd73de2a9722ac5da747f12383d2bfdb93591ee6c58486e0097890f05f2"
+checksum = "1e9cd434a998747dd2c4276bc96ee2e0c7a2eadf3cae88e52be55a05fa9053f5"
 dependencies = [
 "async-compression",
 "bitflags 2.9.1",
@@ -11063,19 +11527,35 @@ dependencies = [
 "http-body-util",
 "http-range-header",
 "httpdate",
- "iri-string",
 "mime",
 "mime_guess",
 "percent-encoding",
 "pin-project-lite",
 "tokio",
 "tokio-util",
- "tower 0.5.2",
 "tower-layer",
 "tower-service",
 "tracing",
 ]

+[[package]]
+name = "tower-http"
+version = "0.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adc82fd73de2a9722ac5da747f12383d2bfdb93591ee6c58486e0097890f05f2"
+dependencies = [
+ "bitflags 2.9.1",
+ "bytes",
+ "futures-util",
+ "http 1.3.1",
+ "http-body 1.0.1",
+ "iri-string",
+ "pin-project-lite",
+ "tower 0.5.2",
+ "tower-layer",
+ "tower-service",
+]
+
 [[package]]
 name = "tower-layer"
 version = "0.3.3"
@@ -11181,14 +11661,14 @@ dependencies = [

 [[package]]
 name = "tracing-subscriber"
-version = "0.3.20"
+version = "0.3.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2054a14f5307d601f88daf0553e1cbf472acc4f2c51afab632431cdcd72124d5"
+checksum = "e8189decb5ac0fa7bc8b96b7cb9b2701d60d48805aca84a238004d665fcc4008"
 dependencies = [
 "matchers",
- "nu-ansi-term 0.50.1",
+ "nu-ansi-term",
 "once_cell",
- "regex-automata",
+ "regex",
 "sharded-slab",
 "smallvec",
 "thread_local",
@@ -11224,7 +11704,7 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2ec6adcab41b1391b08a308cc6302b79f8095d1673f6947c2dc65ffb028b0b2d"
 dependencies = [
- "nu-ansi-term 0.46.0",
+ "nu-ansi-term",
 "tracing-core",
 "tracing-log 0.1.4",
 "tracing-subscriber",
@@ -12226,7 +12706,7 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb"
 dependencies = [
- "windows-sys 0.48.0",
+ "windows-sys 0.59.0",
 ]

 [[package]]
@@ -72,6 +72,10 @@ members = [
    "common/nym-cache",
    "common/nym-connection-monitor",
    "common/nym-id",
+    "common/nym-kcp",
+    "common/nym-lp",
+    "common/nym-lp-common",
+    "common/nym-kkt",
    "common/nym-metrics",
    "common/nym_offline_compact_ecash",
    "common/nymnoise",
@@ -150,7 +154,7 @@ members = [
    "tools/internal/contract-state-importer/importer-cli",
    "tools/internal/contract-state-importer/importer-contract",
    "tools/internal/mixnet-connectivity-check",
-#    "tools/internal/sdk-version-bump",
+    #    "tools/internal/sdk-version-bump",
    "tools/internal/ssl-inject",
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
@@ -165,7 +169,7 @@ members = [
    "wasm/mix-fetch",
    "wasm/node-tester",
    "wasm/zknym-lib",
-    "nym-gateway-probe"
+    "nym-gateway-probe",
 ]

 default-members = [
@@ -204,6 +208,7 @@ aes = "0.8.1"
 aes-gcm = "0.10.1"
 aes-gcm-siv = "0.11.1"
 ammonia = "4"
+ansi_term = "0.12"
 anyhow = "1.0.98"
 arc-swap = "1.7.1"
 argon2 = "0.5.0"
@@ -243,6 +248,7 @@ criterion = "0.5"
 csv = "1.3.1"
 ctr = "0.9.1"
 cupid = "0.6.1"
+curve25519-dalek = "4.1.3"
 dashmap = "5.5.3"
 # We want https://github.com/DefGuard/wireguard-rs/pull/64 , but there's no crates.io release being pushed out anymore
 defguard_wireguard_rs = { git = "https://github.com/DefGuard/wireguard-rs.git", rev = "v0.4.7" }
@@ -282,7 +288,9 @@ inventory = "0.3.21"
 ip_network = "0.4.1"
 ipnetwork = "0.20"
 itertools = "0.14.0"
-jwt-simple = { version = "0.12.12", default-features = false, features = ["pure-rust"] }
+jwt-simple = { version = "0.12.12", default-features = false, features = [
+    "pure-rust",
+] }
 k256 = "0.13"
 lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
@@ -292,6 +300,7 @@ mime = "0.3.17"
 moka = { version = "0.12", features = ["future"] }
 nix = "0.27.1"
 notify = "5.1.0"
+num_enum = "0.7.5"
 once_cell = "1.21.3"
 opentelemetry = "0.19.0"
 opentelemetry-jaeger = "0.18.0"
@@ -338,6 +347,7 @@ test-with = { version = "0.15.4", default-features = false }
 tempfile = "3.20"
 thiserror = "2.0"
 time = "0.3.41"
+tls_codec = "0.4.1"
 tokio = "1.47"
 tokio-postgres = "0.7"
 tokio-stream = "0.1.17"
@@ -347,11 +357,11 @@ tokio-tungstenite = { version = "0.20.1" }
 tokio-util = "0.7.15"
 toml = "0.8.22"
 tower = "0.5.2"
-tower-http = "0.6.6"
+tower-http = "0.5.2"
 tracing = "0.1.41"
 tracing-log = "0.2"
 tracing-opentelemetry = "0.19.0"
-tracing-subscriber = "0.3.20"
+tracing-subscriber = "0.3.19"
 tracing-tree = "0.2.2"
 tracing-indicatif = "0.3.9"
 tracing-test = "0.2.5"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.68"
+version = "1.1.66"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.68"
+version = "1.1.66"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 description = "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address"
 edition = "2021"
@@ -75,7 +75,6 @@ workspace = true
 features = ["json", "rustls-tls"]

 [dev-dependencies]
-anyhow = { workspace = true }
 bip39 = { workspace = true }
 cosmrs = { workspace = true, features = ["bip32"] }
 ts-rs = { workspace = true }
@@ -7,7 +7,6 @@ use cosmrs::{tx, AccountId, Coin, Denom};
 use nym_validator_client::http_client;
 use nym_validator_client::nyxd::CosmWasmClient;
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
-use nym_validator_client::signing::signer::OfflineSigner;
 use nym_validator_client::signing::tx_signer::TxSigner;
 use nym_validator_client::signing::SignerData;

@@ -20,8 +19,8 @@ async fn main() {
    let validator = "https://rpc.sandbox.nymtech.net";
    let to_address: AccountId = "n1pefc2utwpy5w78p2kqdsfmpjxfwmn9d39k5mqa".parse().unwrap();

-    let signer = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, signer_mnemonic).unwrap();
-    let signer_address = signer.signer_addresses()[0].clone();
+    let signer = DirectSecp256k1HdWallet::from_mnemonic(prefix, signer_mnemonic);
+    let signer_address = signer.try_derive_accounts().unwrap()[0].address().clone();

    // local 'client' ONLY signing messages
    let tx_signer = signer;
@@ -58,15 +57,9 @@ async fn main() {
        100000u32,
    );

-    let tx_raw = TxSigner::sign_direct(
-        &tx_signer,
-        &signer_address,
-        vec![send_msg],
-        fee,
-        memo,
-        signer_data,
-    )
-    .unwrap();
+    let tx_raw = tx_signer
+        .sign_direct(&signer_address, vec![send_msg], fee, memo, signer_data)
+        .unwrap();
    let tx_bytes = tx_raw.to_bytes().unwrap();

    // compare balances from before and after the tx
@@ -5,7 +5,8 @@ use crate::nyxd::{self, NyxdClient};
 use crate::signing::direct_wallet::DirectSecp256k1HdWallet;
 use crate::signing::signer::{NoSigner, OfflineSigner};
 use crate::{
-    DirectSigningReqwestRpcValidatorClient, QueryReqwestRpcValidatorClient, ValidatorClientError,
+    DirectSigningReqwestRpcValidatorClient, QueryReqwestRpcValidatorClient, ReqwestRpcClient,
+    ValidatorClientError,
 };
 use nym_api_requests::ecash::models::{
    AggregatedCoinIndicesSignatureResponse, AggregatedExpirationDateSignatureResponse,
@@ -163,7 +164,7 @@ impl Client<HttpRpcClient, DirectSecp256k1HdWallet> {
    ) -> Result<DirectSigningHttpRpcValidatorClient, ValidatorClientError> {
        let rpc_client = http_client(config.nyxd_url.as_str())?;
        let prefix = &config.nyxd_config.chain_details.bech32_account_prefix;
-        let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)?;
+        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);

        Ok(Self::new_signing_with_rpc_client(
            config, rpc_client, wallet,
@@ -176,13 +177,12 @@ impl Client<HttpRpcClient, DirectSecp256k1HdWallet> {
    }
 }

-#[allow(deprecated)]
-impl Client<crate::ReqwestRpcClient, DirectSecp256k1HdWallet> {
+impl Client<ReqwestRpcClient, DirectSecp256k1HdWallet> {
    pub fn new_reqwest_signing(
        config: Config,
        mnemonic: bip39::Mnemonic,
    ) -> DirectSigningReqwestRpcValidatorClient {
-        let rpc_client = crate::ReqwestRpcClient::new(config.nyxd_url.clone());
+        let rpc_client = ReqwestRpcClient::new(config.nyxd_url.clone());
        let prefix = &config.nyxd_config.chain_details.bech32_account_prefix;
        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);

@@ -203,10 +203,9 @@ impl Client<HttpRpcClient> {
    }
 }

-#[allow(deprecated)]
-impl Client<crate::ReqwestRpcClient> {
+impl Client<ReqwestRpcClient> {
    pub fn new_reqwest_query(config: Config) -> QueryReqwestRpcValidatorClient {
-        let rpc_client = crate::ReqwestRpcClient::new(config.nyxd_url.clone());
+        let rpc_client = ReqwestRpcClient::new(config.nyxd_url.clone());
        Self::new_with_rpc_client(config, rpc_client)
    }
 }
@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::nym_api;
-use crate::signing::direct_wallet::DirectSecp256k1HdWalletError;
 pub use tendermint_rpc::error::Error as TendermintRpcError;
 use thiserror::Error;

@@ -27,12 +26,6 @@ pub enum ValidatorClientError {

    #[error("No validator API url has been provided")]
    NoAPIUrlAvailable,
-
-    #[error("failed to derive signing accounts: {source}")]
-    AccountDerivationFailure {
-        #[from]
-        source: DirectSecp256k1HdWalletError,
-    },
 }

 impl From<nym_api::error::NymAPIError> for ValidatorClientError {
@@ -12,7 +12,6 @@ pub mod rpc;
 pub mod signing;

 pub use crate::error::ValidatorClientError;
-#[allow(deprecated)]
 pub use crate::rpc::reqwest::ReqwestRpcClient;
 pub use crate::signing::direct_wallet::DirectSecp256k1HdWallet;
 pub use client::{Client, Config, EcashApiClient};
@@ -39,13 +38,9 @@ pub type DirectSigningHttpRpcValidatorClient = Client<HttpRpcClient, DirectSecp2
 #[cfg(feature = "http-client")]
 pub type DirectSigningHttpRpcNyxdClient = nyxd::NyxdClient<HttpRpcClient, DirectSecp256k1HdWallet>;

-#[allow(deprecated)]
 pub type QueryReqwestRpcValidatorClient = Client<ReqwestRpcClient>;
-#[allow(deprecated)]
 pub type QueryReqwestRpcNyxdClient = nyxd::NyxdClient<ReqwestRpcClient>;

-#[allow(deprecated)]
 pub type DirectSigningReqwestRpcValidatorClient = Client<ReqwestRpcClient, DirectSecp256k1HdWallet>;
-#[allow(deprecated)]
 pub type DirectSigningReqwestRpcNyxdClient =
    nyxd::NyxdClient<ReqwestRpcClient, DirectSecp256k1HdWallet>;
@@ -178,7 +178,7 @@ where
            .ok_or_else(|| NyxdError::unavailable_contract_address("dkg contract"))?;

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];

        self.execute(signer_address, dkg_contract_address, &msg, fee, memo, funds)
            .await
@@ -99,7 +99,7 @@ where
            .ok_or_else(|| NyxdError::unavailable_contract_address("coconut bandwidth contract"))?;

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];

        self.execute(
            signer_address,
@@ -95,7 +95,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];
        self.execute(
            signer_address,
            group_contract_address,
@@ -667,7 +667,7 @@ where
        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
        let memo = msg.default_memo();

-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];
        self.execute(
            signer_address,
            mixnet_contract_address,
@@ -133,7 +133,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];
        self.execute(
            signer_address,
            multisig_contract_address,
@@ -165,7 +165,7 @@ where

        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));

-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];
        self.execute(
            signer_address,
            performance_contract_address,
@@ -375,7 +375,7 @@ where
        let fee = fee.unwrap_or(Fee::Auto(Some(self.simulated_gas_multiplier())));
        let memo = msg.name().to_string();

-        let signer_address = &self.signer_addresses()[0];
+        let signer_address = &self.signer_addresses()?[0];
        self.execute(
            signer_address,
            vesting_contract_address,
@@ -324,7 +324,7 @@ where
 {
    type Error = S::Error;

-    fn get_accounts(&self) -> &[AccountData] {
+    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
        self.signer.get_accounts()
    }

@@ -19,7 +19,7 @@ use crate::signing::signer::NoSigner;
 use crate::signing::signer::OfflineSigner;
 use crate::signing::tx_signer::TxSigner;
 use crate::signing::AccountData;
-use crate::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient};
+use crate::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient, ReqwestRpcClient};
 use async_trait::async_trait;
 use cosmrs::tendermint::{abci, evidence::Evidence, Genesis};
 use cosmrs::tx::{Raw, SignDoc};
@@ -158,13 +158,12 @@ impl NyxdClient<HttpClient> {
    }
 }

-#[allow(deprecated)]
-impl NyxdClient<crate::ReqwestRpcClient> {
+impl NyxdClient<ReqwestRpcClient> {
    pub fn connect_reqwest(
        config: Config,
        endpoint: Url,
    ) -> Result<QueryReqwestRpcNyxdClient, NyxdError> {
-        let client = crate::ReqwestRpcClient::new(endpoint);
+        let client = ReqwestRpcClient::new(endpoint);

        Ok(NyxdClient {
            client: MaybeSigningClient::new(client, (&config).into()),
@@ -196,19 +195,18 @@ impl NyxdClient<HttpClient, DirectSecp256k1HdWallet> {
        let client = http_client(endpoint)?;

        let prefix = &config.chain_details.bech32_account_prefix;
-        let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)?;
+        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
        Ok(Self::connect_with_signer(config, client, wallet))
    }
 }

-#[allow(deprecated)]
-impl NyxdClient<crate::ReqwestRpcClient, DirectSecp256k1HdWallet> {
+impl NyxdClient<ReqwestRpcClient, DirectSecp256k1HdWallet> {
    pub fn connect_reqwest_with_mnemonic(
        config: Config,
        endpoint: Url,
        mnemonic: bip39::Mnemonic,
    ) -> DirectSigningReqwestRpcNyxdClient {
-        let client = crate::ReqwestRpcClient::new(endpoint);
+        let client = ReqwestRpcClient::new(endpoint);

        let prefix = &config.chain_details.bech32_account_prefix;
        let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
@@ -393,12 +391,17 @@ where
    S: OfflineSigner + Send + Sync,
    NyxdError: From<<S as OfflineSigner>::Error>,
 {
-    pub fn signing_account(&self) -> Result<&AccountData, NyxdError> {
+    pub fn signing_account(&self) -> Result<AccountData, NyxdError> {
        Ok(self.find_account(&self.address())?)
    }

    pub fn address(&self) -> AccountId {
-        self.client.signer_addresses()[0].clone()
+        match self.client.signer_addresses() {
+            Ok(addresses) => addresses[0].clone(),
+            Err(_) => {
+                panic!("key derivation failure")
+            }
+        }
    }

    pub fn mix_coin(&self, amount: u128) -> Coin {
@@ -864,7 +867,7 @@ where
 {
    type Error = S::Error;

-    fn get_accounts(&self) -> &[AccountData] {
+    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
        self.client.get_accounts()
    }

@@ -42,15 +42,12 @@ macro_rules! perform_with_compat {
    }};
 }

-// the separate implementation is now completely redundant
-#[deprecated(note = "use HttpClient directly instead")]
 pub struct ReqwestRpcClient {
    compat: CompatMode,
    inner: reqwest::Client,
    url: Url,
 }

-#[allow(deprecated)]
 impl ReqwestRpcClient {
    pub fn new(url: Url) -> Self {
        ReqwestRpcClient {
@@ -134,7 +131,6 @@ impl TendermintRpcErrorMap for reqwest::Error {
    }
 }

-#[allow(deprecated)]
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 impl TendermintRpcClient for ReqwestRpcClient {
@@ -2,18 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::signing::signer::{OfflineSigner, SigningError};
-use crate::signing::{
-    derive_extended_private_key, derive_keypair, AccountData, Secp256k1Derivation, Secp256k1Keypair,
-};
-use bip32::XPrv;
-use cosmrs::bip32::DerivationPath;
+use crate::signing::{AccountData, Secp256k1Derivation};
+use cosmrs::bip32::{DerivationPath, XPrv};
+use cosmrs::crypto::secp256k1::SigningKey;
+use cosmrs::crypto::PublicKey;
 use cosmrs::tx;
 use cosmrs::tx::SignDoc;
 use nym_config::defaults;
-use std::borrow::Cow;
 use thiserror::Error;
 use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};

+type Secp256k1Keypair = (SigningKey, PublicKey);
+
 #[derive(Debug, Error)]
 pub enum DirectSecp256k1HdWalletError {
    #[error(transparent)]
@@ -36,22 +36,28 @@ pub enum DirectSecp256k1HdWalletError {
 }

 // TODO: maybe lock this one behind feature flag?
-#[derive(Zeroize, ZeroizeOnDrop)]
+#[derive(Debug, Clone, Zeroize, ZeroizeOnDrop)]
 pub struct DirectSecp256k1HdWallet {
    /// Base secret
    secret: bip39::Mnemonic,

-    /// Derived accounts
+    /// BIP39 seed
+    seed: [u8; 64],
+
+    // An unfortunate result of immature rust async story is that async traits (only available in the separate package)
+    // can't yet figure out everything and if we stored our derived account data on the struct,
+    // that would include the secret key which is a dyn EcdsaSigner and hence not Sync making the wallet
+    // not Sync and if used on the signing client in an async trait, it wouldn't be Send
+    /// Derivation instructions
    #[zeroize(skip)]
-    // unfortunately `dyn EcdsaSigner` does not guarantee Zeroize
-    accounts: Vec<AccountData>,
+    accounts: Vec<Secp256k1Derivation>,
 }

 impl OfflineSigner for DirectSecp256k1HdWallet {
    type Error = DirectSecp256k1HdWalletError;

-    fn get_accounts(&self) -> &[AccountData] {
-        &self.accounts
+    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
+        self.try_derive_accounts()
    }

    fn sign_direct_with_account(
@@ -71,27 +77,55 @@ impl DirectSecp256k1HdWallet {
    }

    /// Restores a wallet from the given BIP39 mnemonic using default options.
-    #[deprecated(
-        note = "this function can potentially panic if accounts can't be derived correctly. please use .checked_from_mnemonic() instead"
-    )]
    pub fn from_mnemonic(prefix: &str, mnemonic: bip39::Mnemonic) -> Self {
-        // unfortunately due to backwards compatibility requirements,
-        // we can't change signature of this method
-        #[allow(deprecated)]
        DirectSecp256k1HdWalletBuilder::new(prefix).build(mnemonic)
    }

-    /// Restores a wallet from the given BIP39 mnemonic using default options.
-    pub fn checked_from_mnemonic(
-        prefix: &str,
-        mnemonic: bip39::Mnemonic,
-    ) -> Result<Self, DirectSecp256k1HdWalletError> {
-        DirectSecp256k1HdWalletBuilder::new(prefix).try_build(mnemonic)
-    }
-
    pub fn generate(prefix: &str, word_count: usize) -> Result<Self, DirectSecp256k1HdWalletError> {
        let mneomonic = bip39::Mnemonic::generate(word_count)?;
-        Self::checked_from_mnemonic(prefix, mneomonic)
+        Ok(Self::from_mnemonic(prefix, mneomonic))
+    }
+
+    fn derive_keypair(
+        &self,
+        hd_path: &DerivationPath,
+    ) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError> {
+        let extended_private_key = XPrv::derive_from_path(self.seed, hd_path)?;
+
+        let private_key: SigningKey = extended_private_key.into();
+        let public_key = private_key.public_key();
+
+        Ok((private_key, public_key))
+    }
+
+    pub fn derive_extended_private_key(
+        &self,
+        hd_path: &DerivationPath,
+    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
+        Ok(XPrv::derive_from_path(self.seed, hd_path)?)
+    }
+
+    pub fn try_derive_accounts(&self) -> Result<Vec<AccountData>, DirectSecp256k1HdWalletError> {
+        let mut accounts = Vec::with_capacity(self.accounts.len());
+        for derivation_info in &self.accounts {
+            let keypair = self.derive_keypair(&derivation_info.hd_path)?;
+
+            // it seems this can only fail if the provided account prefix is invalid
+            let address = keypair
+                .1
+                .account_id(&derivation_info.prefix)
+                .map_err(
+                    |source| DirectSecp256k1HdWalletError::AccountDerivationError { source },
+                )?;
+
+            accounts.push(AccountData {
+                address,
+                public_key: keypair.1,
+                private_key: keypair.0,
+            })
+        }
+
+        Ok(accounts)
    }

    pub fn secret(&self) -> &bip39::Mnemonic {
@@ -108,43 +142,6 @@ impl DirectSecp256k1HdWallet {
    pub fn mnemonic_string(&self) -> Zeroizing<String> {
        Zeroizing::new(self.secret.to_string())
    }
-
-    pub fn account_seed<'a, P: Into<Cow<'a, str>>>(
-        &self,
-        bip39_password: P,
-    ) -> Zeroizing<[u8; 64]> {
-        Zeroizing::new(self.secret.to_seed(bip39_password))
-    }
-
-    /// Derive an extended private key from the stored account secret assuming no bip39 password
-    #[deprecated(
-        note = "use derive_extended_private_key_with_password to ensure correct derivation if used bip39 password"
-    )]
-    pub fn derive_extended_private_key(
-        &self,
-        hd_path: &DerivationPath,
-    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
-        let seed = self.account_seed("");
-        derive_extended_private_key(seed, hd_path)
-    }
-
-    pub fn derive_keypair<'a, P: Into<Cow<'a, str>>>(
-        &self,
-        hd_path: &DerivationPath,
-        bip39_password: P,
-    ) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError> {
-        let seed = self.account_seed(bip39_password);
-        derive_keypair(seed, hd_path)
-    }
-
-    pub fn derive_extended_private_key_with_password<'a, P: Into<Cow<'a, str>>>(
-        &self,
-        hd_path: &DerivationPath,
-        bip39_password: P,
-    ) -> Result<XPrv, DirectSecp256k1HdWalletError> {
-        let seed = self.account_seed(bip39_password);
-        derive_extended_private_key(seed, hd_path)
-    }
 }

 #[must_use]
@@ -191,39 +188,23 @@ impl DirectSecp256k1HdWalletBuilder {
        self
    }

-    #[deprecated(
-        note = "this function can potentially panic if accounts can't be derived correctly. please use .try_build() instead"
-    )]
    pub fn build(self, mnemonic: bip39::Mnemonic) -> DirectSecp256k1HdWallet {
-        // unfortunately due to backwards compatibility requirements,
-        // we can't change signature of this method
-        #[allow(clippy::expect_used)]
-        self.try_build(mnemonic)
-            .expect("account derivation failure")
-    }
-
-    pub fn try_build(
-        self,
-        mnemonic: bip39::Mnemonic,
-    ) -> Result<DirectSecp256k1HdWallet, DirectSecp256k1HdWalletError> {
-        let seed = Zeroizing::new(mnemonic.to_seed(&self.bip39_password));
+        let seed = mnemonic.to_seed(&self.bip39_password);
        let prefix = self.prefix.clone();
        let accounts = self
            .hd_paths
            .iter()
-            .map(|hd_path| {
-                Secp256k1Derivation {
-                    hd_path: hd_path.clone(),
-                    prefix: prefix.clone(),
-                }
-                .try_derive_account(&seed)
+            .map(|hd_path| Secp256k1Derivation {
+                hd_path: hd_path.clone(),
+                prefix: prefix.clone(),
            })
-            .collect::<Result<_, _>>()?;
+            .collect();

-        Ok(DirectSecp256k1HdWallet {
+        DirectSecp256k1HdWallet {
            accounts,
+            seed,
            secret: mnemonic,
-        })
+        }
    }
 }

@@ -234,7 +215,7 @@ mod tests {
    use super::*;

    #[test]
-    fn generating_account_addresses() -> anyhow::Result<()> {
+    fn generating_account_addresses() {
        // test vectors produced from our js wallet
        let mnemonics = ["crush minute paddle tobacco message debate cabin peace bar jacket execute twenty winner view sure mask popular couch penalty fragile demise fresh pizza stove",
            "acquire rebel spot skin gun such erupt pull swear must define ill chief turtle today flower chunk truth battle claw rigid detail gym feel",
@@ -249,10 +230,11 @@ mod tests {
            "n17n9flp6jflljg6fp05dsy07wcprf2uuu8g40rf",
        ];
        for (idx, mnemonic) in mnemonics.iter().enumerate() {
-            let wallet =
-                DirectSecp256k1HdWallet::checked_from_mnemonic(&prefix, mnemonic.parse()?)?;
-            assert_eq!(wallet.signer_addresses()[0], addrs[idx].parse().unwrap());
+            let wallet = DirectSecp256k1HdWallet::from_mnemonic(&prefix, mnemonic.parse().unwrap());
+            assert_eq!(
+                wallet.try_derive_accounts().unwrap()[0].address,
+                addrs[idx].parse().unwrap()
+            )
        }
-        Ok(())
    }
 }
@@ -1,8 +1,6 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::signing::direct_wallet::DirectSecp256k1HdWalletError;
-use bip32::XPrv;
 use cosmrs::bip32::DerivationPath;
 use cosmrs::crypto::secp256k1::SigningKey;
 use cosmrs::crypto::PublicKey;
@@ -14,64 +12,14 @@ pub mod direct_wallet;
 pub mod signer;
 pub mod tx_signer;

-pub(crate) type Secp256k1Keypair = (SigningKey, PublicKey);
-
 /// Derivation information required to derive a keypair and an address from a mnemonic.
 #[derive(Debug, Clone)]
-pub(crate) struct Secp256k1Derivation {
+struct Secp256k1Derivation {
    hd_path: DerivationPath,
    prefix: String,
 }

-impl Secp256k1Derivation {
-    pub(crate) fn try_derive_account<S>(
-        &self,
-        seed: S,
-    ) -> Result<AccountData, DirectSecp256k1HdWalletError>
-    where
-        S: AsRef<[u8]>,
-    {
-        let keypair = derive_keypair(seed, &self.hd_path)?;
-
-        // it seems this can only fail if the provided account prefix is invalid
-        let address = keypair
-            .1
-            .account_id(&self.prefix)
-            .map_err(|source| DirectSecp256k1HdWalletError::AccountDerivationError { source })?;
-
-        Ok(AccountData {
-            address,
-            public_key: keypair.1,
-            private_key: keypair.0,
-        })
-    }
-}
-
-pub fn derive_keypair<S>(
-    seed: S,
-    hd_path: &DerivationPath,
-) -> Result<Secp256k1Keypair, DirectSecp256k1HdWalletError>
-where
-    S: AsRef<[u8]>,
-{
-    let extended_private_key = derive_extended_private_key(seed, hd_path)?;
-
-    let private_key: SigningKey = extended_private_key.into();
-    let public_key = private_key.public_key();
-
-    Ok((private_key, public_key))
-}
-
-pub fn derive_extended_private_key<S>(
-    seed: S,
-    hd_path: &DerivationPath,
-) -> Result<XPrv, DirectSecp256k1HdWalletError>
-where
-    S: AsRef<[u8]>,
-{
-    Ok(XPrv::derive_from_path(seed, hd_path)?)
-}
-
+// TODO: is this struct going to be derivable with other signer types?
 pub struct AccountData {
    pub address: AccountId,

@@ -33,18 +33,23 @@ pub enum SignerType {
 pub trait OfflineSigner {
    type Error: From<SigningError>;

-    fn signer_addresses(&self) -> Vec<AccountId> {
-        self.get_accounts()
-            .iter()
-            .map(|account| account.address.clone())
-            .collect()
+    // I really dislike existence of this function because it makes you re-derive your key **twice** for each contract transaction
+    fn signer_addresses(&self) -> Result<Vec<AccountId>, Self::Error> {
+        let derived_addresses = self
+            .get_accounts()?
+            .into_iter()
+            .map(|account| account.address)
+            .collect();
+        Ok(derived_addresses)
    }

-    fn get_accounts(&self) -> &[AccountData];
+    fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error>;

-    fn find_account(&self, signer_address: &AccountId) -> Result<&AccountData, Self::Error> {
-        self.get_accounts()
-            .iter()
+    fn find_account(&self, signer_address: &AccountId) -> Result<AccountData, Self::Error> {
+        // TODO: we could really use some zeroize action here
+        let accounts = self.get_accounts()?;
+        accounts
+            .into_iter()
            .find(|account| &account.address == signer_address)
            .ok_or_else(|| {
                SigningError::AccountNotFound {
@@ -71,7 +76,7 @@ pub trait OfflineSigner {
        message: M,
    ) -> Result<Signature, Self::Error> {
        let signer = self.find_account(signer_address)?;
-        self.sign_raw_with_account(signer, message)
+        self.sign_raw_with_account(&signer, message)
    }

    fn sign_direct(
@@ -80,7 +85,7 @@ pub trait OfflineSigner {
        sign_doc: SignDoc,
    ) -> Result<tx::Raw, Self::Error> {
        let signer = self.find_account(signer_address)?;
-        self.sign_direct_with_account(signer, sign_doc)
+        self.sign_direct_with_account(&signer, sign_doc)
    }

    // unless explicitly defined, each signing method is unsupported
@@ -117,7 +122,7 @@ pub struct NoSigner;
 // impl OfflineSigner for NoSigner {
 //     type Error = SignerUnavailable;
 //
-//     fn get_accounts(&self) -> &[AccountData] {
+//     fn get_accounts(&self) -> Result<Vec<AccountData>, Self::Error> {
 //         return Err(SignerUnavailable);
 //     }
 // }
@@ -50,7 +50,7 @@ pub trait TxSigner: OfflineSigner {
        )
        .map_err(|source| SigningError::SignDocFailure { source })?;

-        self.sign_direct_with_account(account_from_signer, sign_doc)
+        self.sign_direct_with_account(&account_from_signer, sign_doc)
    }
 }

@@ -3,7 +3,6 @@

 use clap::Parser;
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
-use nym_validator_client::signing::signer::OfflineSigner;

 #[derive(Debug, Parser)]
 pub struct Args {
@@ -16,10 +15,9 @@ pub fn create_account(args: Args, prefix: &str) {
    let word_count = args.word_count.unwrap_or(24);
    let mnemonic = bip39::Mnemonic::generate(word_count).expect("failed to generate mnemonic!");

-    let wallet = DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic)
-        .expect("failed to derive accounts!");
+    let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);

    // Output address and mnemonics into separate lines for easier parsing
    println!("{}", wallet.mnemonic_string().as_str());
-    println!("{}", wallet.signer_addresses()[0]);
+    println!("{}", wallet.try_derive_accounts().unwrap()[0].address());
 }
@@ -1,13 +1,13 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::context::QueryClient;
-use crate::utils::show_error;
 use clap::Parser;
 use log::{error, info};
 use nym_validator_client::nyxd::{AccountId, CosmWasmClient};
 use nym_validator_client::signing::direct_wallet::DirectSecp256k1HdWallet;
-use nym_validator_client::signing::signer::OfflineSigner;
+
+use crate::context::QueryClient;
+use crate::utils::show_error;

 #[derive(Debug, Parser)]
 pub struct Args {
@@ -50,19 +50,20 @@ pub async fn get_pubkey(
 }

 pub fn get_pubkey_from_mnemonic(address: AccountId, prefix: &str, mnemonic: bip39::Mnemonic) {
-    let wallet = match DirectSecp256k1HdWallet::checked_from_mnemonic(prefix, mnemonic) {
-        Ok(wallet) => wallet,
-        Err(err) => {
-            error!("Failed to derive accounts. {err}");
-            return;
+    let wallet = DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic);
+    match wallet.try_derive_accounts() {
+        Ok(accounts) => match accounts.iter().find(|a| *a.address() == address) {
+            Some(account) => {
+                println!("{}", account.public_key().to_string());
+            }
+            None => {
+                error!("Could not derive key that matches {address}")
+            }
+        },
+        Err(e) => {
+            error!("Failed to derive accounts. {e}");
        }
-    };
-
-    let Ok(account) = wallet.find_account(&address) else {
-        error!("Could not derive key that matches {address}");
-        return;
-    };
-    println!("{}", account.public_key().to_string());
+    }
 }

 pub async fn get_pubkey_from_chain(address: AccountId, client: &QueryClient) {
@@ -27,6 +27,9 @@ pub struct Args {
    #[clap(long)]
    pub identity_key: String,

+    #[clap(long, help = "LP (Lewes Protocol) listener port (default: 41264)")]
+    pub lp_port: Option<u16>,
+
    #[clap(long)]
    pub profit_margin_percent: Option<u64>,

@@ -57,10 +60,13 @@ pub async fn bond_nymnode(args: Args, client: SigningClient) {
        return;
    }

+    let lp_address = args.lp_port.map(|port| format!("{}:{}", args.host, port));
+
    let nymnode = nym_mixnet_contract_common::NymNode {
        host: args.host,
        custom_http_port: args.http_api_port,
        identity_key: args.identity_key,
+        lp_address,
    };

    let coin = Coin::new(args.amount, denom);
@@ -25,6 +25,9 @@ pub struct Args {
    #[clap(long)]
    pub custom_http_api_port: Option<u16>,

+    #[clap(long, help = "LP (Lewes Protocol) listener port (default: 41264)")]
+    pub lp_port: Option<u16>,
+
    #[clap(long)]
    pub profit_margin_percent: Option<u64>,

@@ -47,10 +50,13 @@ pub struct Args {
 pub async fn create_payload(args: Args, client: SigningClient) {
    let denom = client.current_chain_details().mix_denom.base.as_str();

+    let lp_address = args.lp_port.map(|port| format!("{}:{}", args.host, port));
+
    let mixnode = nym_mixnet_contract_common::NymNode {
        host: args.host,
        custom_http_port: args.custom_http_api_port,
        identity_key: args.identity_key,
+        lp_address,
    };

    let coin = Coin::new(args.amount, denom);
@@ -19,6 +19,16 @@ pub struct Args {
    // equivalent to setting `custom_http_port` to `None`
    #[clap(long)]
    pub restore_default_http_port: bool,
+
+    #[clap(
+        long,
+        help = "LP (Lewes Protocol) listener address (format: host:port)"
+    )]
+    pub lp_address: Option<String>,
+
+    // equivalent to setting `lp_address` to `None`
+    #[clap(long)]
+    pub restore_default_lp_address: bool,
 }

 pub async fn update_config(args: Args, client: SigningClient) {
@@ -39,6 +49,8 @@ pub async fn update_config(args: Args, client: SigningClient) {
        host: args.host,
        custom_http_port: args.custom_http_port,
        restore_default_http_port: args.restore_default_http_port,
+        lp_address: args.lp_address,
+        restore_default_lp_address: args.restore_default_lp_address,
    };

    let res = client
@@ -36,35 +36,32 @@ pub fn sign(args: Args, prefix: &str, mnemonic: Option<bip39::Mnemonic>) {
        return;
    }

-    let wallet = match DirectSecp256k1HdWallet::checked_from_mnemonic(
-        prefix,
-        mnemonic.expect("mnemonic not set"),
-    ) {
-        Ok(wallet) => wallet,
-        Err(err) => {
-            error!("Could not derive an account key from the mnemonic: {err}");
-            return;
-        }
-    };
-    match wallet.get_accounts().first() {
-        Some(account) => {
-            let msg = args.message.into_bytes();
-            match wallet.sign_raw_with_account(account, msg) {
-                Ok(signature) => {
-                    let output = SignatureOutputJson {
-                        account_id: account.address().to_string(),
-                        public_key: account.public_key(),
-                        signature_as_hex: signature.to_string(),
-                    };
-                    println!("{}", json!(output));
-                }
-                Err(e) => {
-                    error!("Failed to sign message. {e}");
+    let wallet =
+        DirectSecp256k1HdWallet::from_mnemonic(prefix, mnemonic.expect("mnemonic not set"));
+    match wallet.try_derive_accounts() {
+        Ok(accounts) => match accounts.first() {
+            Some(account) => {
+                let msg = args.message.into_bytes();
+                match wallet.sign_raw_with_account(account, msg) {
+                    Ok(signature) => {
+                        let output = SignatureOutputJson {
+                            account_id: account.address().to_string(),
+                            public_key: account.public_key(),
+                            signature_as_hex: signature.to_string(),
+                        };
+                        println!("{}", json!(output));
+                    }
+                    Err(e) => {
+                        error!("Failed to sign message. {e}");
+                    }
                }
            }
-        }
-        None => {
-            error!("Could not derive an account key from the mnemonic",)
+            None => {
+                error!("Could not derive an account key from the mnemonic",)
+            }
+        },
+        Err(e) => {
+            error!("Failed to derive accounts. {e}");
        }
    }
 }
@@ -1,3 +1,7 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.

-export type NodeConfigUpdate = { host: string | null, custom_http_port: number | null, restore_default_http_port: boolean, };
+export type NodeConfigUpdate = { host: string | null, custom_http_port: number | null, restore_default_http_port: boolean, 
+/**
+ * LP listener address for direct gateway connections (format: "host:port")
+ */
+lp_address: string | null, restore_default_lp_address: boolean, };
@@ -17,4 +17,9 @@ custom_http_port: number | null,
 /**
 * Base58-encoded ed25519 EdDSA public key.
 */
-identity_key: string, };
+identity_key: string, 
+/**
+ * Optional LP (Lewes Protocol) listener address for direct gateway connections.
+ * Format: "host:port", for example "1.1.1.1:41264" or "gateway.example.com:41264"
+ */
+lp_address: string | null, };
@@ -373,6 +373,11 @@ pub struct NymNode {
    /// Base58-encoded ed25519 EdDSA public key.
    #[cfg_attr(feature = "utoipa", schema(value_type = String))]
    pub identity_key: IdentityKey,
+
+    /// Optional LP (Lewes Protocol) listener address for direct gateway connections.
+    /// Format: "host:port", for example "1.1.1.1:41264" or "gateway.example.com:41264"
+    #[serde(default)]
+    pub lp_address: Option<String>,
    // TODO: I don't think we want to include sphinx keys here,
    // given we want to rotate them and keeping that in sync with contract will be a PITA
 }
@@ -405,6 +410,7 @@ impl From<MixNode> for NymNode {
            host: value.host,
            custom_http_port: Some(value.http_api_port),
            identity_key: value.identity_key,
+            lp_address: None,
        }
    }
 }
@@ -415,6 +421,7 @@ impl From<Gateway> for NymNode {
            host: value.host,
            custom_http_port: None,
            identity_key: value.identity_key,
+            lp_address: None,
        }
    }
 }
@@ -437,6 +444,13 @@ pub struct NodeConfigUpdate {
    // equivalent to setting `custom_http_port` to `None`
    #[serde(default)]
    pub restore_default_http_port: bool,
+
+    /// LP listener address for direct gateway connections (format: "host:port")
+    pub lp_address: Option<String>,
+
+    // equivalent to setting `lp_address` to `None`
+    #[serde(default)]
+    pub restore_default_lp_address: bool,
 }

 #[cw_serde]
@@ -30,6 +30,7 @@ nym-crypto = { path = "../crypto", features = ["asymmetric"] }
 nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
 nym-gateway-requests = { path = "../gateway-requests" }
 nym-gateway-storage = { path = "../gateway-storage" }
+nym-metrics = { path = "../nym-metrics" }
 nym-task = { path = "../task" }
 nym-validator-client = { path = "../client-libs/validator-client" }
 nym-upgrade-mode-check = { path = "../upgrade-mode-check" }
@@ -59,9 +59,13 @@ impl traits::EcashManager for EcashManager {
            .verify(aggregated_verification_key)
            .map_err(|err| match err {
                CompactEcashError::ExpirationDateSignatureValidity => {
+                    nym_metrics::inc!("ecash_verification_failures_invalid_date_signature");
                    EcashTicketError::MalformedTicketInvalidDateSignatures
                }
-                _ => EcashTicketError::MalformedTicket,
+                _ => {
+                    nym_metrics::inc!("ecash_verification_failures_signature");
+                    EcashTicketError::MalformedTicket
+                }
            })?;

        self.insert_pay_info(credential.pay_info.into(), insert_index)
@@ -249,4 +253,8 @@ impl traits::EcashManager for MockEcashManager {
    }

    fn async_verify(&self, _ticket: ClientTicket) {}
+
+    fn is_mock(&self) -> bool {
+        true
+    }
 }
@@ -222,9 +222,13 @@ impl SharedState {
            RwLockReadGuard::try_map(guard, |data| data.get(&epoch_id).map(|d| &d.master_key))
        {
            trace!("we already had cached api clients for epoch {epoch_id}");
+            nym_metrics::inc!("ecash_verification_key_cache_hits");
            return Ok(mapped);
        }

+        // Cache miss - need to fetch and set epoch data
+        nym_metrics::inc!("ecash_verification_key_cache_misses");
+
        let write_guard = self.set_epoch_data(epoch_id).await?;
        let guard = write_guard.downgrade();

@@ -20,4 +20,10 @@ pub trait EcashManager {
        aggregated_verification_key: &VerificationKeyAuth,
    ) -> Result<(), EcashTicketError>;
    fn async_verify(&self, ticket: ClientTicket);
+
+    /// Returns true if this is a mock ecash manager (for local testing).
+    /// Default implementation returns false.
+    fn is_mock(&self) -> bool {
+        false
+    }
 }
@@ -8,6 +8,7 @@ use nym_credentials::ecash::utils::{EcashTime, cred_exp_date, ecash_today};
 use nym_credentials_interface::{Bandwidth, ClientTicket, TicketType};
 use nym_gateway_requests::models::CredentialSpendingRequest;
 use std::sync::Arc;
+use std::time::Instant;
 use time::{Date, OffsetDateTime};
 use tracing::*;

@@ -21,6 +22,10 @@ pub mod ecash;
 pub mod error;
 pub mod upgrade_mode;

+// Histogram buckets for ecash verification duration (in seconds)
+const ECASH_VERIFICATION_DURATION_BUCKETS: &[f64] =
+    &[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 2.0, 5.0];
+
 pub struct CredentialVerifier {
    credential: CredentialSpendingRequest,
    ecash_verifier: Arc<dyn EcashManager + Send + Sync>,
@@ -64,6 +69,7 @@ impl CredentialVerifier {
            .await?;
        if spent {
            trace!("the credential has already been spent before at this gateway");
+            nym_metrics::inc!("ecash_verification_failures_double_spending");
            return Err(Error::BandwidthCredentialAlreadySpent);
        }
        Ok(())
@@ -105,6 +111,9 @@ impl CredentialVerifier {
    }

    pub async fn verify(&mut self) -> Result<i64> {
+        let start = Instant::now();
+        nym_metrics::inc!("ecash_verification_attempts");
+
        let received_at = OffsetDateTime::now_utc();
        let spend_date = ecash_today();

@@ -113,15 +122,39 @@ impl CredentialVerifier {
        let credential_type = TicketType::try_from_encoded(self.credential.data.payment.t_type)?;

        if self.credential.data.payment.spend_value != 1 {
+            nym_metrics::inc!("ecash_verification_failures_multiple_tickets");
            return Err(Error::MultipleTickets);
        }

-        self.check_credential_spending_date(spend_date.ecash_date())?;
+        if let Err(e) = self.check_credential_spending_date(spend_date.ecash_date()) {
+            nym_metrics::inc!("ecash_verification_failures_invalid_spend_date");
+            return Err(e);
+        }
+
        self.check_local_db_for_double_spending(&serial_number)
            .await?;

        // TODO: do we HAVE TO do it?
-        self.cryptographically_verify_ticket().await?;
+        let verify_result = self.cryptographically_verify_ticket().await;
+
+        // Track verification duration
+        let duration = start.elapsed().as_secs_f64();
+        nym_metrics::add_histogram_obs!(
+            "ecash_verification_duration_seconds",
+            duration,
+            ECASH_VERIFICATION_DURATION_BUCKETS
+        );
+
+        // Track epoch ID - use dynamic metric name via registry
+        let epoch_id = self.credential.data.epoch_id;
+        let epoch_metric = format!(
+            "nym_credential_verification_ecash_epoch_{}_verifications",
+            epoch_id
+        );
+        nym_metrics::metrics_registry().maybe_register_and_inc(&epoch_metric, None);
+
+        // Check verification result after timing
+        verify_result?;

        let ticket_id = self.store_received_ticket(received_at).await?;
        self.async_verify_ticket(ticket_id);
@@ -135,6 +168,8 @@ impl CredentialVerifier {
            .increase_bandwidth(bandwidth, cred_exp_date())
            .await?;

+        nym_metrics::inc!("ecash_verification_success");
+
        Ok(self
            .bandwidth_storage_manager
            .client_bandwidth
@@ -15,6 +15,7 @@ base64.workspace = true
 bs58 = { workspace = true }
 blake3 = { workspace = true, features = ["traits-preview"], optional = true }
 ctr = { workspace = true, optional = true }
+curve25519-dalek = { workspace = true, optional = true }
 digest = { workspace = true, optional = true }
 generic-array = { workspace = true, optional = true }
 hkdf = { workspace = true, optional = true }
@@ -47,7 +48,7 @@ default = []
 aead = ["dep:aead", "aead/std", "aes-gcm-siv", "generic-array"]
 naive_jwt = ["asymmetric", "jwt-simple"]
 serde = ["dep:serde", "serde_bytes", "ed25519-dalek/serde", "x25519-dalek/serde"]
-asymmetric = ["x25519-dalek", "ed25519-dalek", "zeroize"]
+asymmetric = ["x25519-dalek", "ed25519-dalek", "curve25519-dalek", "sha2", "zeroize"]
 hashing = ["blake3", "digest", "hkdf", "hmac", "generic-array", "sha2"]
 stream_cipher = ["aes", "ctr", "cipher", "generic-array"]
 sphinx = ["nym-sphinx-types/sphinx"]
@@ -213,6 +213,37 @@ impl PublicKey {
    ) -> Result<(), SignatureError> {
        self.0.verify(message.as_ref(), &signature.0)
    }
+
+    /// Converts this Ed25519 public key to an X25519 public key for ECDH.
+    ///
+    /// Uses the standard ed25519→x25519 conversion by converting the Edwards point
+    /// to Montgomery form. This is the same approach as libsodium's
+    /// `crypto_sign_ed25519_pk_to_curve25519`.
+    ///
+    /// # Returns
+    /// * `Ok(x25519::PublicKey)` - The converted X25519 public key
+    /// * `Err(Ed25519RecoveryError)` - If the conversion fails (e.g., low-order point)
+    pub fn to_x25519(&self) -> Result<crate::asymmetric::x25519::PublicKey, Ed25519RecoveryError> {
+        use curve25519_dalek::edwards::CompressedEdwardsY;
+
+        // Decompress the Ed25519 point
+        let compressed = CompressedEdwardsY((*self).to_bytes());
+        let edwards_point = compressed.decompress().ok_or_else(|| {
+            Ed25519RecoveryError::MalformedBytes(SignatureError::from_source(
+                "Failed to decompress Ed25519 point".to_string(),
+            ))
+        })?;
+
+        // Convert to Montgomery form
+        let montgomery = edwards_point.to_montgomery();
+
+        // Create X25519 public key
+        crate::asymmetric::x25519::PublicKey::from_bytes(montgomery.as_bytes()).map_err(|_| {
+            Ed25519RecoveryError::MalformedBytes(SignatureError::from_source(
+                "Failed to convert to X25519".to_string(),
+            ))
+        })
+    }
 }

 #[cfg(feature = "sphinx")]
@@ -334,6 +365,28 @@ impl PrivateKey {
        let signature_bytes = self.sign(text).to_bytes();
        bs58::encode(signature_bytes).into_string()
    }
+
+    /// Converts this Ed25519 private key to an X25519 private key for ECDH.
+    ///
+    /// Uses the standard ed25519→x25519 conversion via SHA-512 hash and clamping.
+    /// This is the same approach as libsodium's `crypto_sign_ed25519_sk_to_curve25519`.
+    ///
+    /// # Returns
+    /// The converted X25519 private key
+    pub fn to_x25519(&self) -> crate::asymmetric::x25519::PrivateKey {
+        use sha2::{Digest, Sha512};
+
+        // Hash the Ed25519 secret key with SHA-512
+        let hash = Sha512::digest(self.0);
+
+        // Take first 32 bytes (clamping is done automatically by x25519_dalek::StaticSecret)
+        let mut x25519_bytes = [0u8; 32];
+        x25519_bytes.copy_from_slice(&hash[..32]);
+
+        #[allow(clippy::expect_used)]
+        crate::asymmetric::x25519::PrivateKey::from_bytes(&x25519_bytes)
+            .expect("x25519 key conversion should never fail")
+    }
 }

 #[cfg(feature = "serde")]
@@ -517,4 +570,27 @@ mod tests {

        assert_eq!(sig1.to_vec(), sig2);
    }
+
+    #[test]
+    #[cfg(feature = "rand")]
+    fn test_ed25519_to_x25519_ecdh() {
+        let mut rng = thread_rng();
+
+        // Create two ed25519 keypairs
+        let alice_ed = KeyPair::new(&mut rng);
+        let bob_ed = KeyPair::new(&mut rng);
+
+        // Convert to x25519
+        let alice_x25519_private = alice_ed.private_key().to_x25519();
+        let alice_x25519_public = alice_ed.public_key().to_x25519().unwrap();
+        let bob_x25519_private = bob_ed.private_key().to_x25519();
+        let bob_x25519_public = bob_ed.public_key().to_x25519().unwrap();
+
+        // Perform ECDH both ways
+        let alice_shared = alice_x25519_private.diffie_hellman(&bob_x25519_public);
+        let bob_shared = bob_x25519_private.diffie_hellman(&alice_x25519_public);
+
+        // Both should produce the same shared secret
+        assert_eq!(alice_shared, bob_shared);
+    }
 }
@@ -0,0 +1,98 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Key Derivation Functions using Blake3.
+
+/// Derives a 32-byte key using Blake3's key derivation mode.
+///
+/// Uses Blake3's built-in `derive_key` function with domain separation via context string.
+///
+/// # Arguments
+/// * `context` - Context string for domain separation (e.g., "nym-lp-psk-v1")
+/// * `key_material` - Input key material (shared secret from ECDH, etc.)
+/// * `salt` - Additional salt for freshness (timestamp + nonce)
+///
+/// # Returns
+/// 32-byte derived key suitable for use as PSK
+///
+/// # Example
+/// ```ignore
+/// let psk = derive_key_blake3("nym-lp-psk-v1", shared_secret.as_bytes(), &salt);
+/// ```
+pub fn derive_key_blake3(context: &str, key_material: &[u8], salt: &[u8]) -> [u8; 32] {
+    // Concatenate key_material and salt as input
+    let input = [key_material, salt].concat();
+
+    // Use Blake3's derive_key with context for domain separation
+    // blake3::derive_key returns [u8; 32] directly
+    blake3::derive_key(context, &input)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_deterministic_derivation() {
+        let context = "test-context";
+        let key_material = b"shared_secret_12345";
+        let salt = b"salt_67890";
+
+        let key1 = derive_key_blake3(context, key_material, salt);
+        let key2 = derive_key_blake3(context, key_material, salt);
+
+        assert_eq!(key1, key2, "Same inputs should produce same output");
+    }
+
+    #[test]
+    fn test_different_contexts_produce_different_keys() {
+        let key_material = b"shared_secret";
+        let salt = b"salt";
+
+        let key1 = derive_key_blake3("context1", key_material, salt);
+        let key2 = derive_key_blake3("context2", key_material, salt);
+
+        assert_ne!(
+            key1, key2,
+            "Different contexts should produce different keys"
+        );
+    }
+
+    #[test]
+    fn test_different_salts_produce_different_keys() {
+        let context = "test-context";
+        let key_material = b"shared_secret";
+
+        let key1 = derive_key_blake3(context, key_material, b"salt1");
+        let key2 = derive_key_blake3(context, key_material, b"salt2");
+
+        assert_ne!(key1, key2, "Different salts should produce different keys");
+    }
+
+    #[test]
+    fn test_different_key_material_produces_different_keys() {
+        let context = "test-context";
+        let salt = b"salt";
+
+        let key1 = derive_key_blake3(context, b"secret1", salt);
+        let key2 = derive_key_blake3(context, b"secret2", salt);
+
+        assert_ne!(
+            key1, key2,
+            "Different key material should produce different keys"
+        );
+    }
+
+    #[test]
+    fn test_output_length() {
+        let key = derive_key_blake3("test", b"key", b"salt");
+        assert_eq!(key.len(), 32, "Output should be exactly 32 bytes");
+    }
+
+    #[test]
+    fn test_empty_inputs() {
+        // Should not panic with empty inputs
+        let key = derive_key_blake3("test", b"", b"");
+        assert_eq!(key.len(), 32);
+    }
+}
@@ -10,6 +10,8 @@ pub mod crypto_hash;
 pub mod hkdf;
 #[cfg(feature = "hashing")]
 pub mod hmac;
+#[cfg(feature = "hashing")]
+pub mod kdf;
 #[cfg(all(feature = "asymmetric", feature = "hashing", feature = "stream_cipher"))]
 pub mod shared_key;
 pub mod symmetric;
@@ -896,7 +896,8 @@ impl Client {
    }

    fn matches_current_host(&self, url: &Url) -> bool {
-        if cfg!(feature = "tunneling") {
+        #[cfg(feature = "tunneling")]
+        {
            if let Some(ref front) = self.front
                && front.is_enabled()
            {
@@ -904,7 +905,9 @@ impl Client {
            } else {
                url.host_str() == self.current_url().host_str()
            }
-        } else {
+        }
+        #[cfg(not(feature = "tunneling"))]
+        {
            url.host_str() == self.current_url().host_str()
        }
    }
@@ -0,0 +1,28 @@
+[package]
+name = "nym-kcp"
+version = "0.1.0"
+edition = { workspace = true }
+license = { workspace = true }
+
+[lib]
+name = "nym_kcp"
+path = "src/lib.rs"
+
+[[bin]]
+name = "wire_format"
+path = "bin/wire_format/main.rs"
+
+[[bin]]
+name = "session"
+path = "bin/session/main.rs"
+
+[dependencies]
+tokio-util = { workspace = true, features = ["codec"] }
+byte_string = "1.0"
+bytes = { workspace = true }
+thiserror = { workspace = true }
+log = { workspace = true }
+ansi_term = { workspace = true }
+
+[dev-dependencies]
+env_logger = "0.11"
@@ -0,0 +1,80 @@
+use bytes::BytesMut;
+use log::info;
+use nym_kcp::{packet::KcpPacket, session::KcpSession};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create two KcpSessions, simulating two endpoints
+    let mut local_sess = KcpSession::new(42);
+    let mut remote_sess = KcpSession::new(42);
+
+    // Set an MSS (max segment size) smaller than our data to force fragmentation
+    local_sess.set_mtu(40);
+    remote_sess.set_mtu(40);
+
+    // Some data larger than 30 bytes to demonstrate multi-fragment
+    let big_data = b"The quick brown fox jumps over the lazy dog. This is a test.";
+
+    // --- LOCAL sends data ---
+    info!(
+        "Local: sending data: {:?}",
+        String::from_utf8_lossy(big_data)
+    );
+    local_sess.send(big_data);
+
+    // Update local session's logic at time=0
+    local_sess.update(100);
+
+    // LOCAL fetches outgoing (to be sent across the network)
+    let outgoing_pkts = local_sess.fetch_outgoing();
+    info!("Local: outgoing pkts: {:?}", outgoing_pkts);
+    // Here you'd normally encrypt and send them. We’ll just encode them into a buffer.
+    // Then that buffer is "transferred" to the remote side.
+    let mut wire_buf = BytesMut::new();
+    for pkt in &outgoing_pkts {
+        pkt.encode(&mut wire_buf);
+    }
+
+    // --- REMOTE receives data ---
+    // The remote side "decrypts" (here we just clone) and decodes
+    let mut remote_in = wire_buf.clone();
+
+    // Decode zero or more KcpPackets from remote_in
+    while let Some(decoded_pkt) = KcpPacket::decode(&mut remote_in)? {
+        info!(
+            "Decoded packet, sn: {}, frg: {}",
+            decoded_pkt.sn(),
+            decoded_pkt.frg()
+        );
+        remote_sess.input(&decoded_pkt);
+    }
+
+    // Update remote session to process newly received data
+    remote_sess.update(100);
+
+    // The remote session likely generated ACK packets
+    let ack_pkts = remote_sess.fetch_outgoing();
+
+    // --- LOCAL receives ACKs ---
+    // The local side decodes them
+    let mut ack_buf = BytesMut::new();
+    for pkt in &ack_pkts {
+        pkt.encode(&mut ack_buf);
+    }
+
+    while let Some(decoded_pkt) = KcpPacket::decode(&mut ack_buf)? {
+        local_sess.input(&decoded_pkt);
+    }
+
+    // Update local again with some arbitrary time, e.g. 50 ms later
+    local_sess.update(100);
+
+    // Just for completeness, local might produce more packets, though typically it's just empty now
+    let _ = local_sess.fetch_outgoing();
+
+    // --- REMOTE reads reassembled data ---
+
+    let incoming = remote_sess.fetch_incoming();
+    info!("Remote: incoming pkts: {:?}", incoming);
+
+    Ok(())
+}
@@ -0,0 +1,83 @@
+use std::{
+    fs::File,
+    io::{BufRead as _, BufReader},
+};
+
+use bytes::BytesMut;
+use log::info;
+use nym_kcp::{
+    codec::KcpCodec,
+    packet::{KcpCommand, KcpPacket},
+};
+use tokio_util::codec::{Decoder as _, Encoder as _};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // 1) Open a file and read lines
+    let file = File::open("bin/wire_format/packets.txt")?;
+    let reader = BufReader::new(file);
+
+    // 2) Create our KcpCodec
+    let mut codec = KcpCodec {};
+
+    // We'll use out_buf for encoded data from *all* lines
+    let mut out_buf = BytesMut::new();
+
+    let mut input_lines = vec![];
+
+    // Read lines & encode them all
+    for (i, line) in reader.lines().enumerate() {
+        let line = line?;
+        info!("Original line #{}: {}", i + 1, line);
+
+        // Construct a KcpPacket
+        let pkt = KcpPacket::new(
+            42,
+            KcpCommand::Push,
+            0,
+            128,
+            0,
+            i as u32,
+            0,
+            line.as_bytes().to_vec(),
+        );
+
+        input_lines.push(pkt.clone_data());
+
+        // Encode (serialize) the packet into out_buf
+        codec.encode(pkt, &mut out_buf)?;
+    }
+
+    // === Simulate encryption & transmission ===
+    // In reality, you might do `encrypt(&out_buf)` and then
+    // send it over the network. We'll just clone here:
+    let mut received_buf = out_buf.clone();
+
+    // 3) Now decode (deserialize) all packets at once
+    // For demonstration, read them back out
+    let mut count = 0;
+
+    let mut decoded_lines = vec![];
+
+    #[allow(clippy::while_let_loop)]
+    loop {
+        match codec.decode(&mut received_buf)? {
+            Some(decoded_pkt) => {
+                count += 1;
+                // Convert packet data back to a string
+                let decoded_str = String::from_utf8_lossy(decoded_pkt.data());
+                info!("Decoded line #{}: {}", decoded_pkt.sn() + 1, decoded_str);
+
+                decoded_lines.push(decoded_pkt.clone_data());
+            }
+            None => break,
+        }
+    }
+
+    for (i, j) in input_lines.iter().zip(decoded_lines.iter()) {
+        assert_eq!(i, j);
+    }
+
+    info!("Decoded {} lines total.", count);
+
+    Ok(())
+}
@@ -0,0 +1,10 @@
+packet 1
+packet 2
+packet 3
+packet 4
+packet 5
+packet 6
+packet 7
+packet 8
+packet 9
+packet 10
@@ -0,0 +1,30 @@
+use std::io;
+
+use bytes::BytesMut;
+use tokio_util::codec::{Decoder, Encoder};
+
+use super::packet::KcpPacket;
+
+/// Our codec for encoding/decoding KCP packets
+#[derive(Debug, Default)]
+pub struct KcpCodec;
+
+impl Decoder for KcpCodec {
+    type Item = KcpPacket;
+    type Error = io::Error;
+
+    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Self::Item>, Self::Error> {
+        // We simply delegate to `KcpPacket::decode`
+        KcpPacket::decode(src).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
+    }
+}
+
+impl Encoder<KcpPacket> for KcpCodec {
+    type Error = io::Error;
+
+    fn encode(&mut self, item: KcpPacket, dst: &mut BytesMut) -> Result<(), Self::Error> {
+        // We just call `item.encode` to append the bytes
+        item.encode(dst);
+        Ok(())
+    }
+}
@@ -0,0 +1,60 @@
+use bytes::BytesMut;
+use log::{debug, trace};
+
+use crate::{error::KcpError, packet::KcpPacket, session::KcpSession};
+
+pub struct KcpDriver {
+    session: KcpSession,
+    buffer: BytesMut,
+}
+
+impl KcpDriver {
+    pub fn conv_id(&self) -> Result<u32, KcpError> {
+        Ok(self.session.conv)
+    }
+
+    pub fn send(&mut self, data: &[u8]) {
+        self.session.send(data);
+    }
+
+    pub fn input(&mut self, data: &[u8]) -> Result<Vec<KcpPacket>, KcpError> {
+        self.buffer.extend_from_slice(data);
+        let mut pkts = Vec::new();
+        while let Ok(Some(pkt)) = KcpPacket::decode(&mut self.buffer) {
+            debug!(
+                "Decoded packet, cmd: {}, sn: {}, frg: {}",
+                pkt.command(),
+                pkt.sn(),
+                pkt.frg()
+            );
+            self._input(&pkt)?;
+            pkts.push(pkt);
+        }
+        Ok(pkts)
+    }
+
+    fn _input(&mut self, pkt: &KcpPacket) -> Result<(), KcpError> {
+        self.session.input(pkt);
+        Ok(())
+    }
+
+    pub fn fetch_outgoing(&mut self) -> Vec<KcpPacket> {
+        trace!(
+            "ts_flush: {}, ts_current: {}",
+            self.session.ts_flush(),
+            self.session.ts_current()
+        );
+        self.session.fetch_outgoing()
+    }
+
+    pub fn update(&mut self, tick: u64) {
+        self.session.update(tick as u32);
+    }
+
+    pub fn new(session: KcpSession) -> Self {
+        KcpDriver {
+            session,
+            buffer: BytesMut::new(),
+        }
+    }
+}
@@ -0,0 +1,10 @@
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum KcpError {
+    #[error("Invalid KCP command value: {0}")]
+    InvalidCommand(u8),
+
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+}
@@ -0,0 +1,5 @@
+pub mod codec;
+pub mod driver;
+pub mod error;
+pub mod packet;
+pub mod session;
@@ -0,0 +1,219 @@
+use bytes::{Buf, BufMut, BytesMut};
+use log::{debug, trace};
+
+use super::error::KcpError;
+
+pub const KCP_HEADER: usize = 24;
+
+/// Typed enumeration for KCP commands.
+#[repr(u8)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum KcpCommand {
+    Push = 81, // cmd: push data
+    Ack = 82,  // cmd: ack
+    Wask = 83, // cmd: window probe (ask)
+    Wins = 84, // cmd: window size (tell)
+}
+
+impl std::fmt::Display for KcpCommand {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            KcpCommand::Push => write!(f, "Push"),
+            KcpCommand::Ack => write!(f, "Ack"),
+            KcpCommand::Wask => write!(f, "Window Probe (ask)"),
+            KcpCommand::Wins => write!(f, "Window Size (tell)"),
+        }
+    }
+}
+
+impl TryFrom<u8> for KcpCommand {
+    type Error = KcpError;
+
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        match value {
+            81 => Ok(KcpCommand::Push),
+            82 => Ok(KcpCommand::Ack),
+            83 => Ok(KcpCommand::Wask),
+            84 => Ok(KcpCommand::Wins),
+            _ => Err(KcpError::InvalidCommand(value)),
+        }
+    }
+}
+
+#[allow(clippy::from_over_into)]
+impl Into<u8> for KcpCommand {
+    fn into(self) -> u8 {
+        self as u8
+    }
+}
+
+/// A single KCP packet (on-wire format).
+#[derive(Debug, Clone)]
+pub struct KcpPacket {
+    conv: u32,
+    cmd: KcpCommand,
+    frg: u8,
+    wnd: u16,
+    ts: u32,
+    sn: u32,
+    una: u32,
+    data: Vec<u8>,
+}
+
+#[allow(clippy::too_many_arguments)]
+impl KcpPacket {
+    pub fn new(
+        conv: u32,
+        cmd: KcpCommand,
+        frg: u8,
+        wnd: u16,
+        ts: u32,
+        sn: u32,
+        una: u32,
+        data: Vec<u8>,
+    ) -> Self {
+        Self {
+            conv,
+            cmd,
+            frg,
+            wnd,
+            ts,
+            sn,
+            una,
+            data,
+        }
+    }
+
+    pub fn command(&self) -> KcpCommand {
+        self.cmd
+    }
+
+    pub fn data(&self) -> &[u8] {
+        &self.data
+    }
+
+    pub fn clone_data(&self) -> Vec<u8> {
+        self.data.clone()
+    }
+
+    pub fn conv(&self) -> u32 {
+        self.conv
+    }
+
+    pub fn cmd(&self) -> KcpCommand {
+        self.cmd
+    }
+
+    pub fn frg(&self) -> u8 {
+        self.frg
+    }
+
+    pub fn wnd(&self) -> u16 {
+        self.wnd
+    }
+
+    pub fn ts(&self) -> u32 {
+        self.ts
+    }
+
+    pub fn sn(&self) -> u32 {
+        self.sn
+    }
+
+    pub fn una(&self) -> u32 {
+        self.una
+    }
+}
+
+impl Default for KcpPacket {
+    fn default() -> Self {
+        // We must pick some default command, e.g. `Push`.
+        // Or omit `Default` if you don't need it.
+        KcpPacket {
+            conv: 0,
+            cmd: KcpCommand::Push,
+            frg: 0,
+            wnd: 0,
+            ts: 0,
+            sn: 0,
+            una: 0,
+            data: Vec::new(),
+        }
+    }
+}
+
+impl KcpPacket {
+    /// Attempt to decode a `KcpPacket` from `src`.
+    /// Returns Ok(Some(pkt)) if fully available, Ok(None) if not enough data,
+    /// or Err(...) if there's an invalid command or other error.
+    pub fn decode(src: &mut BytesMut) -> Result<Option<Self>, KcpError> {
+        trace!("Decoding buffer with len: {}", src.len());
+        if src.len() < KCP_HEADER {
+            // Not enough for even the header, this is usually fine, more data will arrive
+            debug!("Not enough data for header");
+            return Ok(None);
+        }
+
+        // Peek into the first 28 bytes
+        let mut header = &src[..KCP_HEADER];
+
+        let conv = header.get_u32_le();
+        let cmd_byte = header.get_u8();
+        let frg = header.get_u8();
+        let wnd = header.get_u16_le();
+        let ts = header.get_u32_le();
+        let sn = header.get_u32_le();
+        let una = header.get_u32_le();
+        let len = header.get_u32_le() as usize;
+
+        let total_needed = KCP_HEADER + len;
+        if src.len() < total_needed {
+            // We don't have the full packet yet
+            debug!(
+                "Not enough data for packet, want {}, have {}",
+                total_needed,
+                src.len()
+            );
+            return Ok(None);
+        }
+
+        // Convert the raw u8 into our KcpCommand enum
+        let cmd = KcpCommand::try_from(cmd_byte)?;
+
+        // Now we can read out the data portion
+        let data = src[KCP_HEADER..KCP_HEADER + len].to_vec();
+
+        // Advance the buffer so it no longer contains this packet
+        src.advance(total_needed);
+
+        Ok(Some(Self {
+            conv,
+            cmd,
+            frg,
+            wnd,
+            ts,
+            sn,
+            una,
+            data,
+        }))
+    }
+
+    /// Encode this packet into `dst`.
+    pub fn encode(&self, dst: &mut BytesMut) {
+        let total_len = KCP_HEADER + self.data.len();
+        trace!("Encoding packet: {:?}, len: {}", self, total_len);
+        dst.reserve(total_len);
+
+        dst.put_u32_le(self.conv);
+        dst.put_u8(self.cmd.into()); // Convert enum -> u8
+        dst.put_u8(self.frg);
+        dst.put_u16_le(self.wnd);
+        dst.put_u32_le(self.ts);
+        dst.put_u32_le(self.sn);
+        dst.put_u32_le(self.una);
+        dst.put_u32_le(self.data.len() as u32);
+        dst.extend_from_slice(&self.data);
+
+        trace!("Encoded packet: {:?}, len: {}", dst, dst.len());
+    }
+}
@@ -0,0 +1,49 @@
+[package]
+name = "nym-kkt"
+version = "0.1.0"
+authors = ["Georgio Nicolas <georgio@nymtech.net>"]
+edition = { workspace = true }
+license.workspace = true
+
+[dependencies]
+arc-swap = { workspace = true }
+bytes = { workspace = true }
+futures = { workspace = true }
+tracing = { workspace = true }
+pin-project = { workspace = true }
+blake3 = { workspace = true }
+aead = { workspace = true }
+strum = { workspace = true, features = ["derive"] }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+tokio-util = { workspace = true, features = ["codec"] }
+
+
+
+# internal
+nym-crypto = { path = "../crypto", features = ["asymmetric", "serde"]}
+nym-sphinx = { path = "../nymsphinx" }
+
+libcrux-traits = { git = "https://github.com/cryspen/libcrux" }
+libcrux-kem = { git = "https://github.com/cryspen/libcrux" }
+libcrux-psq = { git = "https://github.com/cryspen/libcrux", features = ["test-utils"] }
+libcrux-sha3 = { git = "https://github.com/cryspen/libcrux" }
+libcrux-ml-kem = { git = "https://github.com/cryspen/libcrux" }
+libcrux-ecdh = { git = "https://github.com/cryspen/libcrux", features = ["codec"]}
+libcrux-chacha20poly1305 = { git = "https://github.com/cryspen/libcrux" }
+
+rand = "0.9.2"
+curve25519-dalek = {version = "4.1.3", features = ["rand_core", "serde"] }
+zeroize = { workspace = true, features = ["zeroize_derive"] }
+classic-mceliece-rust = { git = "https://github.com/georgio/classic-mceliece-rust", features = ["mceliece460896f","zeroize"]}
+
+
+[dev-dependencies]
+criterion = {workspace = true}
+
+[[bench]]
+name = "benches"
+harness = false
+
+[lints]
+workspace = true
@@ -0,0 +1,518 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use criterion::{Criterion, criterion_group, criterion_main};
+
+use nym_crypto::asymmetric::ed25519;
+use nym_kkt::{
+    ciphersuite::{Ciphersuite, EncapsulationKey, HashFunction, KEM, SignatureScheme},
+    context::KKTMode,
+    frame::KKTFrame,
+    key_utils::{generate_keypair_libcrux, generate_keypair_mceliece, hash_encapsulation_key},
+    session::{
+        anonymous_initiator_process, initiator_ingest_response, initiator_process,
+        responder_ingest_message, responder_process,
+    },
+};
+use rand::prelude::*;
+
+pub fn gen_ed25519_keypair(c: &mut Criterion) {
+    c.bench_function("Generate Ed25519 Keypair", |b| {
+        b.iter(|| {
+            let mut s: [u8; 32] = [0u8; 32];
+            rand::rng().fill_bytes(&mut s);
+            ed25519::KeyPair::from_secret(s, 0)
+        });
+    });
+}
+
+pub fn gen_mlkem768_keypair(c: &mut Criterion) {
+    c.bench_function("Generate MlKem768 Keypair", |b| {
+        b.iter(|| {
+            libcrux_kem::key_gen(libcrux_kem::Algorithm::MlKem768, &mut rand::rng()).unwrap()
+        });
+    });
+}
+
+pub fn kkt_benchmark(c: &mut Criterion) {
+    let mut rng = rand::rng();
+
+    // generate ed25519 keys
+    let mut secret_initiator: [u8; 32] = [0u8; 32];
+    rng.fill_bytes(&mut secret_initiator);
+    let initiator_ed25519_keypair = ed25519::KeyPair::from_secret(secret_initiator, 0);
+
+    let mut secret_responder: [u8; 32] = [0u8; 32];
+    rng.fill_bytes(&mut secret_responder);
+    let responder_ed25519_keypair = ed25519::KeyPair::from_secret(secret_responder, 1);
+    for kem in [KEM::MlKem768, KEM::XWing, KEM::X25519, KEM::McEliece] {
+        for hash_function in [
+            HashFunction::Blake3,
+            HashFunction::SHA256,
+            HashFunction::SHAKE128,
+            HashFunction::SHAKE256,
+        ] {
+            let ciphersuite = Ciphersuite::resolve_ciphersuite(
+                kem,
+                hash_function,
+                SignatureScheme::Ed25519,
+                None,
+            )
+            .unwrap();
+
+            // generate kem public keys
+
+            let (responder_kem_public_key, initiator_kem_public_key) = match kem {
+                KEM::MlKem768 => (
+                    EncapsulationKey::MlKem768(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                    EncapsulationKey::MlKem768(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                ),
+                KEM::XWing => (
+                    EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                    EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                ),
+                KEM::X25519 => (
+                    EncapsulationKey::X25519(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                    EncapsulationKey::X25519(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                ),
+                KEM::McEliece => (
+                    EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                    EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                ),
+            };
+
+            let i_kem_key_bytes = initiator_kem_public_key.encode();
+
+            let r_kem_key_bytes = responder_kem_public_key.encode();
+
+            let i_dir_hash = hash_encapsulation_key(
+                &ciphersuite.hash_function(),
+                ciphersuite.hash_len(),
+                &i_kem_key_bytes,
+            );
+
+            let r_dir_hash = hash_encapsulation_key(
+                &ciphersuite.hash_function(),
+                ciphersuite.hash_len(),
+                &r_kem_key_bytes,
+            );
+
+            // Anonymous Initiator, OneWay
+            {
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Generate Request",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| anonymous_initiator_process(&mut rng, ciphersuite).unwrap());
+                    },
+                );
+
+                let (mut i_context, i_frame) =
+                    anonymous_initiator_process(&mut rng, ciphersuite).unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Encode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| b.iter(|| i_frame.to_bytes()),
+                );
+
+                let i_frame_bytes = i_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Decode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| b.iter(|| KKTFrame::from_bytes(&i_frame_bytes).unwrap()),
+                );
+
+                let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Responder Ingest Frame",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_ingest_message(&r_context, None, None, &i_frame_r).unwrap()
+                        });
+                    },
+                );
+
+                let (mut r_context, _) =
+                    responder_ingest_message(&r_context, None, None, &i_frame_r).unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Responder Generate Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_process(
+                                &mut r_context,
+                                i_frame_r.session_id_ref(),
+                                responder_ed25519_keypair.private_key(),
+                                &responder_kem_public_key,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+                let r_frame = responder_process(
+                    &mut r_context,
+                    i_frame_r.session_id_ref(),
+                    responder_ed25519_keypair.private_key(),
+                    &responder_kem_public_key,
+                )
+                .unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Responder Encode Frame",
+                        kem, hash_function
+                    ),
+                    |b| b.iter(|| r_frame.to_bytes()),
+                );
+
+                let r_bytes = r_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Anonymous Initiator: Initiator Ingest Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            initiator_ingest_response(
+                                &mut i_context,
+                                responder_ed25519_keypair.public_key(),
+                                &r_dir_hash,
+                                &r_bytes,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let obtained_key = initiator_ingest_response(
+                    &mut i_context,
+                    responder_ed25519_keypair.public_key(),
+                    &r_dir_hash,
+                    &r_bytes,
+                )
+                .unwrap();
+
+                assert_eq!(obtained_key.encode(), r_kem_key_bytes)
+            }
+            // Initiator, OneWay
+            {
+                let (mut i_context, i_frame) = initiator_process(
+                    &mut rng,
+                    KKTMode::OneWay,
+                    ciphersuite,
+                    initiator_ed25519_keypair.private_key(),
+                    None,
+                )
+                .unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Generate Request",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            initiator_process(
+                                &mut rng,
+                                KKTMode::OneWay,
+                                ciphersuite,
+                                initiator_ed25519_keypair.private_key(),
+                                None,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Encode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| b.iter(|| i_frame.to_bytes()),
+                );
+
+                let i_frame_bytes = i_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Decode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| b.iter(|| KKTFrame::from_bytes(&i_frame_bytes).unwrap()),
+                );
+
+                let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Responder Ingest Frame",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_ingest_message(
+                                &r_context,
+                                Some(initiator_ed25519_keypair.public_key()),
+                                None,
+                                &i_frame_r,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let (mut r_context, r_obtained_key) = responder_ingest_message(
+                    &r_context,
+                    Some(initiator_ed25519_keypair.public_key()),
+                    None,
+                    &i_frame_r,
+                )
+                .unwrap();
+
+                assert!(r_obtained_key.is_none());
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Responder Generate Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_process(
+                                &mut r_context,
+                                i_frame_r.session_id_ref(),
+                                responder_ed25519_keypair.private_key(),
+                                &responder_kem_public_key,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let r_frame = responder_process(
+                    &mut r_context,
+                    i_frame_r.session_id_ref(),
+                    responder_ed25519_keypair.private_key(),
+                    &responder_kem_public_key,
+                )
+                .unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Responder Encode Frame",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| r_frame.to_bytes());
+                    },
+                );
+
+                let r_bytes = r_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator OneWay: Initiator Ingest Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            initiator_ingest_response(
+                                &mut i_context,
+                                responder_ed25519_keypair.public_key(),
+                                &r_dir_hash,
+                                &r_bytes,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let i_obtained_key = initiator_ingest_response(
+                    &mut i_context,
+                    responder_ed25519_keypair.public_key(),
+                    &r_dir_hash,
+                    &r_bytes,
+                )
+                .unwrap();
+
+                assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+            }
+
+            // Initiator, Mutual
+            {
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Generate Request",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            initiator_process(
+                                &mut rng,
+                                KKTMode::Mutual,
+                                ciphersuite,
+                                initiator_ed25519_keypair.private_key(),
+                                Some(&initiator_kem_public_key),
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let (mut i_context, i_frame) = initiator_process(
+                    &mut rng,
+                    KKTMode::Mutual,
+                    ciphersuite,
+                    initiator_ed25519_keypair.private_key(),
+                    Some(&initiator_kem_public_key),
+                )
+                .unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Encode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| i_frame.to_bytes());
+                    },
+                );
+
+                let i_frame_bytes = i_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Decode Frame - Request",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| KKTFrame::from_bytes(&i_frame_bytes).unwrap());
+                    },
+                );
+
+                let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Responder Ingest Frame",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_ingest_message(
+                                &r_context,
+                                Some(initiator_ed25519_keypair.public_key()),
+                                Some(&i_dir_hash),
+                                &i_frame_r,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let (mut r_context, r_obtained_key) = responder_ingest_message(
+                    &r_context,
+                    Some(initiator_ed25519_keypair.public_key()),
+                    Some(&i_dir_hash),
+                    &i_frame_r,
+                )
+                .unwrap();
+
+                assert_eq!(r_obtained_key.unwrap().encode(), i_kem_key_bytes);
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Responder Generate Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            responder_process(
+                                &mut r_context,
+                                i_frame_r.session_id_ref(),
+                                responder_ed25519_keypair.private_key(),
+                                &responder_kem_public_key,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let r_frame = responder_process(
+                    &mut r_context,
+                    i_frame_r.session_id_ref(),
+                    responder_ed25519_keypair.private_key(),
+                    &responder_kem_public_key,
+                )
+                .unwrap();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Responder Encode Frame",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            r_frame.to_bytes();
+                        });
+                    },
+                );
+
+                let r_bytes = r_frame.to_bytes();
+
+                c.bench_function(
+                    &format!(
+                        "{}, {} | Initiator Mutual: Initiator Ingest Response",
+                        kem, hash_function
+                    ),
+                    |b| {
+                        b.iter(|| {
+                            initiator_ingest_response(
+                                &mut i_context,
+                                responder_ed25519_keypair.public_key(),
+                                &r_dir_hash,
+                                &r_bytes,
+                            )
+                            .unwrap()
+                        });
+                    },
+                );
+
+                let obtained_key = initiator_ingest_response(
+                    &mut i_context,
+                    responder_ed25519_keypair.public_key(),
+                    &r_dir_hash,
+                    &r_bytes,
+                )
+                .unwrap();
+
+                assert_eq!(obtained_key.encode(), r_kem_key_bytes)
+            }
+        }
+    }
+}
+
+criterion_group!(
+    benches,
+    gen_ed25519_keypair,
+    gen_mlkem768_keypair,
+    kkt_benchmark
+);
+criterion_main!(benches);
@@ -0,0 +1,301 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::fmt::Display;
+
+use libcrux_kem::{Algorithm, MlKem768PublicKey};
+use nym_crypto::asymmetric::ed25519;
+
+use crate::error::KKTError;
+
+pub const HASH_LEN_256: usize = 32;
+pub const CIPHERSUITE_ENCODING_LEN: usize = 4;
+
+pub const CURVE25519_KEY_LEN: usize = 32;
+
+#[derive(Clone, Copy, Debug)]
+pub enum HashFunction {
+    Blake3,
+    SHAKE128,
+    SHAKE256,
+    SHA256,
+}
+impl Display for HashFunction {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            HashFunction::Blake3 => "Blake3",
+            HashFunction::SHAKE128 => "SHAKE128",
+            HashFunction::SHAKE256 => "SHAKE256",
+            HashFunction::SHA256 => "SHA256",
+        })
+    }
+}
+
+pub enum EncapsulationKey<'a> {
+    MlKem768(libcrux_kem::PublicKey),
+    XWing(libcrux_kem::PublicKey),
+    X25519(libcrux_kem::PublicKey),
+    McEliece(classic_mceliece_rust::PublicKey<'a>),
+}
+
+pub enum DecapsulationKey<'a> {
+    MlKem768(libcrux_kem::PrivateKey),
+    XWing(libcrux_kem::PrivateKey),
+    X25519(libcrux_kem::PrivateKey),
+    McEliece(classic_mceliece_rust::SecretKey<'a>),
+}
+impl<'a> EncapsulationKey<'a> {
+    pub(crate) fn decode(kem: KEM, bytes: &[u8]) -> Result<Self, KKTError> {
+        match kem {
+            KEM::McEliece => {
+                if bytes.len() != classic_mceliece_rust::CRYPTO_PUBLICKEYBYTES {
+                    Err(KKTError::KEMError {
+                        info: "Received McEliece Encapsulation Key with Invalid Length",
+                    })
+                } else {
+                    let mut public_key_bytes =
+                        Box::new([0u8; classic_mceliece_rust::CRYPTO_PUBLICKEYBYTES]);
+                    // Size must be correct due to KKTFrame::from_bytes(message_bytes)?
+                    public_key_bytes.clone_from_slice(bytes);
+                    Ok(EncapsulationKey::McEliece(
+                        classic_mceliece_rust::PublicKey::from(public_key_bytes),
+                    ))
+                }
+            }
+            KEM::X25519 => Ok(EncapsulationKey::X25519(libcrux_kem::PublicKey::decode(
+                map_kem_to_libcrux_kem(kem),
+                bytes,
+            )?)),
+            KEM::MlKem768 => Ok(EncapsulationKey::MlKem768(libcrux_kem::PublicKey::decode(
+                map_kem_to_libcrux_kem(kem),
+                bytes,
+            )?)),
+            KEM::XWing => Ok(EncapsulationKey::XWing(libcrux_kem::PublicKey::decode(
+                map_kem_to_libcrux_kem(kem),
+                bytes,
+            )?)),
+        }
+    }
+
+    pub fn encode(&self) -> Vec<u8> {
+        match self {
+            EncapsulationKey::XWing(public_key)
+            | EncapsulationKey::MlKem768(public_key)
+            | EncapsulationKey::X25519(public_key) => public_key.encode(),
+            EncapsulationKey::McEliece(public_key) => Vec::from(public_key.as_array()),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum SignatureScheme {
+    Ed25519,
+}
+impl Display for SignatureScheme {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            SignatureScheme::Ed25519 => "Ed25519",
+        })
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum KEM {
+    MlKem768,
+    XWing,
+    X25519,
+    McEliece,
+}
+
+impl Display for KEM {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            KEM::MlKem768 => "MlKem768",
+            KEM::XWing => "XWing",
+            KEM::X25519 => "x25519",
+            KEM::McEliece => "McEliece",
+        })
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct Ciphersuite {
+    hash_function: HashFunction,
+    signature_scheme: SignatureScheme,
+    kem: KEM,
+    hash_length: u8,
+    encapsulation_key_length: usize,
+    signing_key_length: usize,
+    verification_key_length: usize,
+    signature_length: usize,
+}
+
+impl Ciphersuite {
+    pub fn kem_key_len(&self) -> usize {
+        self.encapsulation_key_length
+    }
+
+    pub fn signature_len(&self) -> usize {
+        self.signature_length
+    }
+    pub fn signing_key_len(&self) -> usize {
+        self.signing_key_length
+    }
+    pub fn verification_key_len(&self) -> usize {
+        self.verification_key_length
+    }
+    pub fn hash_function(&self) -> HashFunction {
+        self.hash_function
+    }
+    pub fn kem(&self) -> KEM {
+        self.kem
+    }
+    pub fn signature_scheme(&self) -> SignatureScheme {
+        self.signature_scheme
+    }
+    pub fn hash_len(&self) -> usize {
+        self.hash_length as usize
+    }
+
+    pub fn resolve_ciphersuite(
+        kem: KEM,
+        hash_function: HashFunction,
+        signature_scheme: SignatureScheme,
+        // This should be None 99.9999% of the time
+        custom_hash_length: Option<u8>,
+    ) -> Result<Self, KKTError> {
+        let hash_len = match custom_hash_length {
+            Some(l) => {
+                if l < 16 {
+                    return Err(KKTError::InsecureHashLen);
+                } else {
+                    l
+                }
+            }
+            None => HASH_LEN_256 as u8,
+        };
+        Ok(Self {
+            hash_function,
+            signature_scheme,
+            kem,
+            hash_length: hash_len,
+            encapsulation_key_length: match kem {
+                // 1184 bytes
+                KEM::MlKem768 => MlKem768PublicKey::len(),
+                // 1216 bytes = 1184 + 32
+                KEM::XWing => MlKem768PublicKey::len() + CURVE25519_KEY_LEN,
+                // 32 bytes
+                KEM::X25519 => CURVE25519_KEY_LEN,
+                // 524160 bytes
+                KEM::McEliece => classic_mceliece_rust::CRYPTO_PUBLICKEYBYTES,
+            },
+            signing_key_length: match signature_scheme {
+                // 32 bytes
+                SignatureScheme::Ed25519 => ed25519::SECRET_KEY_LENGTH,
+            },
+            verification_key_length: match signature_scheme {
+                // 32 bytes
+                SignatureScheme::Ed25519 => ed25519::PUBLIC_KEY_LENGTH,
+            },
+            signature_length: match signature_scheme {
+                // 64 bytes
+                SignatureScheme::Ed25519 => ed25519::SIGNATURE_LENGTH,
+            },
+        })
+    }
+    pub fn encode(&self) -> [u8; 4] {
+        // [kem, hash, hashlen, sig]
+        [
+            match self.kem {
+                KEM::XWing => 0,
+                KEM::MlKem768 => 1,
+                KEM::McEliece => 2,
+                KEM::X25519 => 255,
+            },
+            match self.hash_function {
+                HashFunction::Blake3 => 0,
+                HashFunction::SHAKE256 => 1,
+                HashFunction::SHAKE128 => 2,
+                HashFunction::SHA256 => 3,
+            },
+            match self.hash_length as usize {
+                HASH_LEN_256 => 0u8,
+                _ => self.hash_length,
+            },
+            match self.signature_scheme {
+                SignatureScheme::Ed25519 => 0,
+            },
+        ]
+    }
+    pub fn decode(encoding: &[u8]) -> Result<Self, KKTError> {
+        if encoding.len() == 4 {
+            let kem = match encoding[0] {
+                0 => KEM::XWing,
+                1 => KEM::MlKem768,
+                2 => KEM::McEliece,
+                255 => KEM::X25519,
+                _ => {
+                    return Err(KKTError::CiphersuiteDecodingError {
+                        info: format!("Undefined KEM: {}", encoding[0]),
+                    });
+                }
+            };
+            let hash_function = match encoding[1] {
+                0 => HashFunction::Blake3,
+                1 => HashFunction::SHAKE256,
+                2 => HashFunction::SHAKE128,
+                3 => HashFunction::SHA256,
+                _ => {
+                    return Err(KKTError::CiphersuiteDecodingError {
+                        info: format!("Undefined Hash Function: {}", encoding[1]),
+                    });
+                }
+            };
+
+            let custom_hash_length = match encoding[2] {
+                0 => None,
+                _ => Some(encoding[2]),
+            };
+
+            let signature_scheme = match encoding[3] {
+                0 => SignatureScheme::Ed25519,
+                _ => {
+                    return Err(KKTError::CiphersuiteDecodingError {
+                        info: format!("Undefined Signature Scheme: {}", encoding[3]),
+                    });
+                }
+            };
+
+            Self::resolve_ciphersuite(kem, hash_function, signature_scheme, custom_hash_length)
+        } else {
+            Err(KKTError::CiphersuiteDecodingError {
+                info: format!(
+                    "Incorrect Encoding Length: actual: {} != expected: {}",
+                    encoding.len(),
+                    CIPHERSUITE_ENCODING_LEN
+                ),
+            })
+        }
+    }
+}
+
+impl Display for Ciphersuite {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(
+            &format!(
+                "{}_{}({})_{}",
+                self.kem, self.hash_function, self.hash_length, self.signature_scheme
+            )
+            .to_ascii_lowercase(),
+        )
+    }
+}
+
+pub const fn map_kem_to_libcrux_kem(kem: KEM) -> Algorithm {
+    match kem {
+        KEM::MlKem768 => Algorithm::MlKem768,
+        KEM::XWing => Algorithm::XWingKemDraft06,
+        KEM::X25519 => Algorithm::X25519,
+        KEM::McEliece => panic!("McEliece is not supported in libcrux_kem"),
+    }
+}
@@ -0,0 +1,258 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::fmt::Display;
+
+use crate::{KKT_VERSION, ciphersuite::Ciphersuite, error::KKTError, frame::KKT_SESSION_ID_LEN};
+
+pub const KKT_CONTEXT_LEN: usize = 7;
+
+#[derive(Clone, Copy, PartialEq, Debug)]
+pub enum KKTStatus {
+    Ok,
+    InvalidRequestFormat,
+    InvalidResponseFormat,
+    InvalidSignature,
+    UnsupportedCiphersuite,
+    UnsupportedKKTVersion,
+    InvalidKey,
+    Timeout,
+}
+
+impl Display for KKTStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            KKTStatus::Ok => "Ok",
+            KKTStatus::InvalidRequestFormat => "Invalid Request Format",
+            KKTStatus::InvalidResponseFormat => "Invalid Response Format",
+            KKTStatus::InvalidSignature => "Invalid Signature",
+            KKTStatus::UnsupportedCiphersuite => "Unsupported Ciphersuite",
+            KKTStatus::UnsupportedKKTVersion => "Unsupported KKT Version",
+            KKTStatus::InvalidKey => "Invalid Key",
+            KKTStatus::Timeout => "Timeout",
+        })
+    }
+}
+#[derive(Clone, Copy, PartialEq, Debug)]
+pub enum KKTRole {
+    Initiator,
+    AnonymousInitiator,
+    Responder,
+}
+
+#[derive(Clone, Copy, PartialEq, Debug)]
+pub enum KKTMode {
+    OneWay,
+    Mutual,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct KKTContext {
+    version: u8,
+    message_sequence: u8,
+    status: KKTStatus,
+    mode: KKTMode,
+    role: KKTRole,
+    ciphersuite: Ciphersuite,
+}
+impl KKTContext {
+    pub fn new(role: KKTRole, mode: KKTMode, ciphersuite: Ciphersuite) -> Result<Self, KKTError> {
+        if role == KKTRole::AnonymousInitiator && mode != KKTMode::OneWay {
+            return Err(KKTError::IncompatibilityError {
+                info: "Anonymous Initiator can only use OneWay mode",
+            });
+        }
+        Ok(Self {
+            version: KKT_VERSION,
+            message_sequence: 0,
+            status: KKTStatus::Ok,
+            mode,
+            role,
+            ciphersuite,
+        })
+    }
+
+    pub fn derive_responder_header(&self) -> Result<Self, KKTError> {
+        let mut responder_header = *self;
+
+        responder_header.increment_message_sequence_count()?;
+        responder_header.role = KKTRole::Responder;
+
+        Ok(responder_header)
+    }
+
+    pub fn increment_message_sequence_count(&mut self) -> Result<(), KKTError> {
+        if self.message_sequence + 1 < (1 << 4) {
+            self.message_sequence += 1;
+            Ok(())
+        } else {
+            Err(KKTError::MessageCountLimitReached)
+        }
+    }
+
+    pub fn update_status(&mut self, status: KKTStatus) {
+        self.status = status;
+    }
+    pub fn version(&self) -> u8 {
+        self.version
+    }
+    pub fn status(&self) -> KKTStatus {
+        self.status
+    }
+    pub fn ciphersuite(&self) -> Ciphersuite {
+        self.ciphersuite
+    }
+    pub fn role(&self) -> KKTRole {
+        self.role
+    }
+    pub fn mode(&self) -> KKTMode {
+        self.mode
+    }
+
+    pub fn body_len(&self) -> usize {
+        if self.status != KKTStatus::Ok
+            || (self.mode == KKTMode::OneWay
+                && (self.role == KKTRole::Initiator || self.role == KKTRole::AnonymousInitiator))
+        {
+            0
+        } else {
+            self.ciphersuite.kem_key_len()
+        }
+    }
+
+    pub fn signature_len(&self) -> usize {
+        match self.role {
+            KKTRole::Initiator | KKTRole::Responder => self.ciphersuite.signature_len(),
+            KKTRole::AnonymousInitiator => 0,
+        }
+    }
+
+    pub fn header_len(&self) -> usize {
+        KKT_CONTEXT_LEN
+    }
+
+    pub fn session_id_len(&self) -> usize {
+        // match self.role {
+        //     KKTRole::Initiator | KKTRole::Responder => SESSION_ID_LENGTH,
+        // It doesn't make sense to send a session_id if we send messages in the clear
+        //     KKTRole::AnonymousInitiator => 0,
+        // }
+        KKT_SESSION_ID_LEN
+    }
+
+    pub fn full_message_len(&self) -> usize {
+        self.body_len() + self.signature_len() + self.header_len() + self.session_id_len()
+    }
+
+    pub fn encode(&self) -> Result<Vec<u8>, KKTError> {
+        let mut header_bytes: Vec<u8> = Vec::with_capacity(KKT_CONTEXT_LEN);
+        if self.message_sequence >= 1 << 4 {
+            return Err(KKTError::MessageCountLimitReached);
+        }
+
+        header_bytes.push((KKT_VERSION << 4) + self.message_sequence);
+
+        header_bytes.push(
+            match self.status {
+                KKTStatus::Ok => 0,
+                KKTStatus::InvalidRequestFormat => 0b0010_0000,
+                KKTStatus::InvalidResponseFormat => 0b0100_0000,
+                KKTStatus::InvalidSignature => 0b0110_0000,
+                KKTStatus::UnsupportedCiphersuite => 0b1000_0000,
+                KKTStatus::UnsupportedKKTVersion => 0b1010_0000,
+                KKTStatus::InvalidKey => 0b1100_0000,
+                KKTStatus::Timeout => 0b1110_0000,
+            } + match self.mode {
+                KKTMode::OneWay => 0,
+                KKTMode::Mutual => 0b0000_0100,
+            } + match self.role {
+                KKTRole::Initiator => 0,
+                KKTRole::Responder => 1,
+                KKTRole::AnonymousInitiator => 2,
+            },
+        );
+
+        header_bytes.extend_from_slice(&self.ciphersuite.encode());
+        header_bytes.push(0);
+        Ok(header_bytes)
+    }
+
+    pub fn try_decode(header_bytes: &[u8]) -> Result<Self, KKTError> {
+        if header_bytes.len() == KKT_CONTEXT_LEN {
+            let kkt_version = header_bytes[0] & 0b1111_0000;
+
+            let message_sequence_counter = header_bytes[0] & 0b0000_1111;
+
+            // We only check if stuff is valid here, not necessarily if it's compatible
+
+            if (kkt_version >> 4) > KKT_VERSION {
+                return Err(KKTError::FrameDecodingError {
+                    info: format!("Header - Invalid KKT Version: {}", kkt_version >> 4),
+                });
+            }
+
+            let status = match header_bytes[1] & 0b1110_0000 {
+                0 => KKTStatus::Ok,
+                0b0010_0000 => KKTStatus::InvalidRequestFormat,
+                0b0100_0000 => KKTStatus::InvalidResponseFormat,
+                0b0110_0000 => KKTStatus::InvalidSignature,
+                0b1000_0000 => KKTStatus::UnsupportedCiphersuite,
+                0b1010_0000 => KKTStatus::UnsupportedKKTVersion,
+                0b1100_0000 => KKTStatus::InvalidKey,
+                0b1110_0000 => KKTStatus::Timeout,
+                _ => {
+                    return Err(KKTError::FrameDecodingError {
+                        info: format!(
+                            "Header - Invalid KKT Status: {}",
+                            header_bytes[1] & 0b1110_0000
+                        ),
+                    });
+                }
+            };
+
+            let role = match header_bytes[1] & 0b0000_0011 {
+                0 => KKTRole::Initiator,
+                1 => KKTRole::Responder,
+                2 => KKTRole::AnonymousInitiator,
+                _ => {
+                    return Err(KKTError::FrameDecodingError {
+                        info: format!(
+                            "Header - Invalid KKT Role: {}",
+                            header_bytes[1] & 0b0000_0011
+                        ),
+                    });
+                }
+            };
+
+            let mode = match (header_bytes[1] & 0b0001_1100) >> 2 {
+                0 => KKTMode::OneWay,
+                1 => KKTMode::Mutual,
+                _ => {
+                    return Err(KKTError::FrameDecodingError {
+                        info: format!(
+                            "Header - Invalid KKT Mode: {}",
+                            (header_bytes[1] & 0b0001_1100) >> 2
+                        ),
+                    });
+                }
+            };
+
+            Ok(KKTContext {
+                version: kkt_version,
+                status,
+                mode,
+                role,
+                ciphersuite: Ciphersuite::decode(&header_bytes[2..6])?,
+                message_sequence: message_sequence_counter,
+            })
+        } else {
+            Err(KKTError::FrameDecodingError {
+                info: format!(
+                    "Header - Invalid Header Length: actual: {} != expected: {}",
+                    header_bytes.len(),
+                    KKT_CONTEXT_LEN
+                ),
+            })
+        }
+    }
+}
@@ -0,0 +1,222 @@
+use blake3::Hasher;
+
+use libcrux_chacha20poly1305::{NONCE_LEN, TAG_LEN};
+
+use nym_sphinx::{PrivateKey, PublicKey};
+
+use rand::{CryptoRng, RngCore};
+use zeroize::Zeroize;
+
+use crate::{
+    ciphersuite::{CURVE25519_KEY_LEN, HASH_LEN_256},
+    context::KKTContext,
+    error::KKTError,
+    frame::KKTFrame,
+};
+
+#[derive(Clone, Copy, Zeroize)]
+pub struct KKTSessionSecret([u8; 32]);
+
+impl KKTSessionSecret {
+    pub fn new(remote_public_key: &PublicKey) -> (Self, PublicKey) {
+        // this doesn't use the newer rand crate
+        let ephemeral_private_key = PrivateKey::random();
+        let ephemeral_public_key = PublicKey::from(&ephemeral_private_key);
+
+        (
+            Self::derive(&ephemeral_private_key, &remote_public_key),
+            ephemeral_public_key,
+        )
+    }
+    pub fn from_bytes(secret: [u8; 32]) -> Self {
+        Self(secret)
+    }
+    pub fn try_derive(private_key: &PrivateKey, public_key: &[u8]) -> Result<Self, KKTError> {
+        let mut pub_key: [u8; 32] = [0u8; 32];
+        pub_key.copy_from_slice(&public_key[0..CURVE25519_KEY_LEN]);
+
+        // Todo: check validity of pk...
+        let pk = PublicKey::from(pub_key);
+        Ok(Self::derive(private_key, &pk))
+    }
+
+    pub fn derive(private_key: &PrivateKey, public_key: &PublicKey) -> Self {
+        let mut shared_secret = private_key.diffie_hellman(&public_key);
+
+        let mut hasher = Hasher::new();
+
+        hasher.update(shared_secret.as_bytes());
+        shared_secret.zeroize();
+
+        Self(hasher.finalize().as_bytes().to_owned())
+    }
+    pub fn as_bytes(&self) -> &[u8; 32] {
+        &self.0
+    }
+}
+
+pub fn encrypt_initial_kkt_frame<R>(
+    rng: &mut R,
+    remote_public_key: &PublicKey,
+    kkt_frame: &KKTFrame,
+) -> Result<(KKTSessionSecret, Vec<u8>), KKTError>
+where
+    R: CryptoRng + RngCore,
+{
+    let (session_secret_key, ephemeral_public_key) = KKTSessionSecret::new(remote_public_key);
+
+    let mut encrypted_frame =
+        encrypt_kkt_frame(rng, &session_secret_key, &kkt_frame, b"KKT_INITIAL_FRAME")?;
+
+    let mut output_buffer = Vec::with_capacity(encrypted_frame.len() + CURVE25519_KEY_LEN);
+    output_buffer.extend_from_slice(ephemeral_public_key.as_bytes());
+    output_buffer.append(&mut encrypted_frame);
+
+    // [     32     |  12   | ciphertext | 16];
+    // [eph_pub_key | nonce | ciphertext | tag];
+    Ok((session_secret_key, output_buffer))
+}
+
+pub fn decrypt_initial_kkt_frame(
+    responder_private_key: &PrivateKey,
+    encrypted_frame_bytes: &[u8],
+) -> Result<(KKTSessionSecret, KKTFrame, KKTContext), KKTError> {
+    if encrypted_frame_bytes.len() < CURVE25519_KEY_LEN + TAG_LEN + NONCE_LEN {
+        return Err(KKTError::AEADError {
+            info: "Encrypted KKT Frame is too short.",
+        });
+    } else {
+        let shared_secret = KKTSessionSecret::try_derive(
+            responder_private_key,
+            &encrypted_frame_bytes[0..CURVE25519_KEY_LEN],
+        )?;
+
+        let (kkt_frame, kkt_context) = decrypt_kkt_frame(
+            &shared_secret,
+            &encrypted_frame_bytes[CURVE25519_KEY_LEN..],
+            b"KKT_INITIAL_FRAME",
+        )?;
+        Ok((shared_secret, kkt_frame, kkt_context))
+    }
+}
+
+pub fn encrypt_kkt_frame<R>(
+    rng: &mut R,
+    secret_key: &KKTSessionSecret,
+    kkt_frame: &KKTFrame,
+    aad: &[u8],
+) -> Result<Vec<u8>, KKTError>
+where
+    R: CryptoRng + RngCore,
+{
+    let kkt_frame_bytes = kkt_frame.to_bytes();
+
+    // generate nonce
+    let mut nonce: [u8; NONCE_LEN] = [0u8; NONCE_LEN];
+    rng.fill_bytes(&mut nonce);
+
+    let mut ciphertext = encrypt(&secret_key.as_bytes(), &kkt_frame_bytes, &aad, &nonce)?;
+
+    // [  12  | ciphertext | 16];
+    // [nonce | ciphertext | tag];
+    let mut output_buffer: Vec<u8> =
+        Vec::with_capacity(NONCE_LEN + kkt_frame_bytes.len() + TAG_LEN);
+
+    output_buffer.extend_from_slice(&nonce);
+    output_buffer.append(&mut ciphertext);
+
+    Ok(output_buffer)
+}
+
+// kkt_frame_bytes should look like this
+// [  12  | ciphertext | 16];
+// [nonce | ciphertext | tag];
+pub fn decrypt_kkt_frame(
+    secret_key: &KKTSessionSecret,
+    kkt_frame_bytes: &[u8],
+    aad: &[u8],
+) -> Result<(KKTFrame, KKTContext), KKTError> {
+    let mut nonce: [u8; NONCE_LEN] = [0u8; NONCE_LEN];
+    nonce.copy_from_slice(&kkt_frame_bytes[0..NONCE_LEN]);
+
+    let plaintext = decrypt(
+        secret_key.as_bytes(),
+        &kkt_frame_bytes[NONCE_LEN..],
+        aad,
+        &nonce,
+    )?;
+
+    KKTFrame::from_bytes(&plaintext)
+}
+
+fn encrypt(
+    secret_key: &[u8; 32],
+    plaintext: &[u8],
+    aad: &[u8],
+    nonce: &[u8; NONCE_LEN],
+) -> Result<Vec<u8>, KKTError> {
+    let mut output_buffer = vec![0; plaintext.len() + TAG_LEN];
+    libcrux_chacha20poly1305::encrypt(&secret_key, &plaintext, &mut output_buffer, &aad, &nonce)?;
+    Ok(output_buffer)
+}
+
+fn decrypt(
+    secret_key: &[u8; 32],
+    ciphertext: &[u8],
+    aad: &[u8],
+    nonce: &[u8; NONCE_LEN],
+) -> Result<Vec<u8>, KKTError> {
+    let mut output_buffer = vec![0; ciphertext.len() - TAG_LEN];
+    libcrux_chacha20poly1305::decrypt(&secret_key, &mut output_buffer, &ciphertext, &aad, &nonce)?;
+    Ok(output_buffer)
+}
+
+#[cfg(test)]
+mod test {
+    use rand::{RngCore, rng};
+
+    use crate::{
+        ciphersuite::HASH_LEN_256,
+        encryption::{KKTSessionSecret, decrypt, encrypt},
+        key_utils::generate_keypair_x25519,
+    };
+
+    #[test]
+    fn test_keygen() {
+        let responder_x25519_keypair = generate_keypair_x25519();
+
+        let (session_secret_key, ephemeral_public_key) =
+            KKTSessionSecret::new(&responder_x25519_keypair.1);
+
+        let shared_secret = KKTSessionSecret::try_derive(
+            &responder_x25519_keypair.0,
+            &ephemeral_public_key.as_bytes().as_slice(),
+        )
+        .unwrap();
+
+        assert_eq!(shared_secret.as_bytes(), session_secret_key.as_bytes())
+    }
+
+    #[test]
+    fn test_encryption() {
+        let mut rng = rng();
+
+        let mut secret_key = [0u8; HASH_LEN_256];
+        rng.fill_bytes(&mut secret_key);
+
+        let mut plaintext = vec![0; 100];
+        rng.fill_bytes(&mut plaintext);
+
+        let mut nonce = [0; 12];
+        rng.fill_bytes(&mut nonce);
+
+        let mut aad = vec![0; 124];
+        rng.fill_bytes(&mut aad);
+
+        let ciphertext = encrypt(&secret_key, &plaintext, &aad, &nonce).unwrap();
+
+        let o_plaintext = decrypt(&secret_key, &ciphertext, &aad, &nonce).unwrap();
+
+        assert_eq!(o_plaintext, plaintext)
+    }
+}
@@ -0,0 +1,121 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::fmt::Debug;
+
+use nym_crypto::asymmetric::x25519::KeyRecoveryError;
+use thiserror::Error;
+
+use crate::context::KKTStatus;
+
+#[derive(Error, Debug)]
+pub enum KKTError {
+    #[error("Signature constructor error")]
+    SigConstructorError,
+    #[error("Signature verification error")]
+    SigVerifError,
+    #[error("Ciphersuite Decoding Error: {}", info)]
+    CiphersuiteDecodingError { info: String },
+    #[error("Insecure Encapsulation Key Hash Length")]
+    InsecureHashLen,
+
+    #[error("KKT Frame Decoding Error: {}", info)]
+    FrameDecodingError { info: String },
+
+    #[error("KKT Frame Encoding Error: {}", info)]
+    FrameEncodingError { info: String },
+
+    #[error("KKT Incompatibility Error: {}", info)]
+    IncompatibilityError { info: &'static str },
+
+    #[error("KKT Responder Flagged Error: {}", status)]
+    ResponderFlaggedError { status: KKTStatus },
+
+    #[error("KKT Message Count Limit Reached")]
+    MessageCountLimitReached,
+
+    #[error("PSQ KEM Error: {}", info)]
+    KEMError { info: &'static str },
+
+    #[error("Local Function Input Error: {}", info)]
+    FunctionInputError { info: &'static str },
+
+    #[error("{}", info)]
+    X25519Error { info: &'static str },
+
+    #[error("{}", info)]
+    AEADError { info: &'static str },
+
+    #[error("Generic libcrux error")]
+    LibcruxError,
+}
+
+impl From<KeyRecoveryError> for KKTError {
+    fn from(err: KeyRecoveryError) -> Self {
+        err.into()
+    }
+}
+
+impl From<libcrux_kem::Error> for KKTError {
+    fn from(err: libcrux_kem::Error) -> Self {
+        match err {
+            libcrux_kem::Error::EcDhError(_) => KKTError::KEMError { info: "ECDH Error" },
+            libcrux_kem::Error::KeyGen => KKTError::KEMError {
+                info: "Key Generation Error",
+            },
+            libcrux_kem::Error::Encapsulate => KKTError::KEMError {
+                info: "Encapsulation Error",
+            },
+            libcrux_kem::Error::Decapsulate => KKTError::KEMError {
+                info: "Decapsulation Error",
+            },
+            libcrux_kem::Error::UnsupportedAlgorithm => KKTError::KEMError {
+                info: "libcrux Unsupported Algorithm",
+            },
+            libcrux_kem::Error::InvalidPrivateKey => KKTError::KEMError {
+                info: "Invalid Private Key",
+            },
+
+            libcrux_kem::Error::InvalidPublicKey => KKTError::KEMError {
+                info: "Invalid Public Key",
+            },
+            libcrux_kem::Error::InvalidCiphertext => KKTError::KEMError {
+                info: "Invalid Ciphertext",
+            },
+        }
+    }
+}
+impl From<libcrux_ecdh::Error> for KKTError {
+    fn from(err: libcrux_ecdh::Error) -> Self {
+        match err {
+            libcrux_ecdh::Error::InvalidPoint => KKTError::KEMError {
+                info: "Invalid Remote Public Key",
+            },
+            _ => KKTError::LibcruxError,
+        }
+    }
+}
+impl From<libcrux_chacha20poly1305::AeadError> for KKTError {
+    fn from(err: libcrux_chacha20poly1305::AeadError) -> Self {
+        KKTError::KEMError {
+            info: match err {
+                libcrux_chacha20poly1305::AeadError::PlaintextTooLarge => {
+                    "Plaintext is longer than u32::MAX"
+                }
+                libcrux_chacha20poly1305::AeadError::CiphertextTooLarge => {
+                    "Ciphertext is longer than u32::MAX"
+                }
+                libcrux_chacha20poly1305::AeadError::AadTooLarge => "Aad is longer than u32::MAX",
+                libcrux_chacha20poly1305::AeadError::CiphertextTooShort => {
+                    "The provided destination ciphertext does not fit the ciphertext and tag"
+                }
+                libcrux_chacha20poly1305::AeadError::PlaintextTooShort => {
+                    "The provided destination plaintext is too short to fit the decrypted plaintext"
+                }
+                libcrux_chacha20poly1305::AeadError::InvalidCiphertext => {
+                    "The ciphertext is not a valid encryption under the given key and nonce."
+                }
+            },
+        }
+    }
+}
@@ -0,0 +1,129 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// | 0 | 1 | 2, 3, 4, 5 | 6 | 7
+// [0] => KKT version (4 bits) + Message Sequence Count (4 bits)
+// [1] => Status (3 bits) + Mode (3 bits) + Role (2 bits)
+// [2..=5] => Ciphersuite
+// [6] => Reserved
+
+use crate::{
+    context::{KKT_CONTEXT_LEN, KKTContext},
+    error::KKTError,
+};
+
+pub const KKT_SESSION_ID_LEN: usize = 16;
+
+pub struct KKTFrame {
+    context: Vec<u8>,
+    session_id: Vec<u8>,
+    body: Vec<u8>,
+    signature: Vec<u8>,
+}
+
+// if oneway and message coming from initiator => body is empty, signature contains signature of context + session id (64 bytes).
+// if message coming from anonymous initiator => body is empty, there is no signature.
+// if mutual and message coming from initiator => body has the initiator's kem public key and the signature is over the context + body + session_id.
+// if coming from responder => body has the responder's kem public key and the signature is over the context + body + session_id.
+
+impl KKTFrame {
+    pub fn new(context: &[u8], body: &[u8], session_id: &[u8], signature: &[u8]) -> Self {
+        Self {
+            context: Vec::from(context),
+            body: Vec::from(body),
+            session_id: Vec::from(session_id),
+            signature: Vec::from(signature),
+        }
+    }
+    pub fn context_ref(&self) -> &[u8] {
+        &self.context
+    }
+    pub fn signature_ref(&self) -> &[u8] {
+        &self.signature
+    }
+    pub fn body_ref(&self) -> &[u8] {
+        &self.body
+    }
+
+    pub fn session_id_ref(&self) -> &[u8] {
+        &self.session_id
+    }
+    pub fn signature_mut(&mut self) -> &mut [u8] {
+        &mut self.signature
+    }
+    pub fn body_mut(&mut self) -> &mut [u8] {
+        &mut self.body
+    }
+
+    pub fn session_id_mut(&mut self) -> &mut [u8] {
+        &mut self.session_id
+    }
+
+    pub fn frame_length(&self) -> usize {
+        self.context.len() + self.session_id.len() + self.body.len() + self.signature.len()
+    }
+
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut bytes = Vec::with_capacity(self.frame_length());
+        bytes.extend_from_slice(&self.context);
+        bytes.extend_from_slice(&self.body);
+        bytes.extend_from_slice(&self.session_id);
+        bytes.extend_from_slice(&self.signature);
+        bytes
+    }
+
+    pub fn from_bytes(bytes: &[u8]) -> Result<(Self, KKTContext), KKTError> {
+        if bytes.len() < KKT_CONTEXT_LEN {
+            Err(KKTError::FrameDecodingError {
+                info: format!(
+                    "Frame is shorter than expected context length: actual {} != expected {}",
+                    bytes.len(),
+                    KKT_CONTEXT_LEN
+                ),
+            })
+        } else {
+            let context_bytes = Vec::from(&bytes[0..KKT_CONTEXT_LEN]);
+
+            let context = KKTContext::try_decode(&context_bytes)?;
+
+            let (mut session_id, mut body, mut signature): (Vec<u8>, Vec<u8>, Vec<u8>) =
+                (vec![], vec![], vec![]);
+
+            if bytes.len() == context.full_message_len() {
+                if context.body_len() > 0 {
+                    body.extend_from_slice(
+                        &bytes[KKT_CONTEXT_LEN..KKT_CONTEXT_LEN + context.body_len()],
+                    );
+                }
+                if context.session_id_len() > 0 {
+                    session_id.extend_from_slice(
+                        &bytes[KKT_CONTEXT_LEN + context.body_len()
+                            ..KKT_CONTEXT_LEN + context.body_len() + context.session_id_len()],
+                    );
+                }
+                if context.signature_len() > 0 {
+                    signature.extend_from_slice(
+                        &bytes[KKT_CONTEXT_LEN + context.body_len() + context.session_id_len()
+                            ..KKT_CONTEXT_LEN
+                                + context.body_len()
+                                + context.session_id_len()
+                                + context.signature_len()],
+                    );
+                }
+
+                Ok((
+                    KKTFrame::new(&context_bytes, &body, &session_id, &signature),
+                    context,
+                ))
+            } else {
+                Err(KKTError::FrameDecodingError {
+                    info: format!(
+                        "Frame is shorter than expected: actual {} != expected {}",
+                        bytes.len(),
+                        context.full_message_len()
+                    ),
+                })
+            }
+        }
+    }
+}
@@ -0,0 +1,122 @@
+use crate::{
+    ciphersuite::{HashFunction, KEM},
+    error::KKTError,
+};
+
+use classic_mceliece_rust::keypair_boxed;
+use libcrux_kem::{Algorithm, key_gen};
+
+use libcrux_sha3;
+use nym_crypto::asymmetric::ed25519;
+use rand::{CryptoRng, RngCore};
+pub fn generate_keypair_ed25519<R>(rng: &mut R, index: Option<u32>) -> ed25519::KeyPair
+where
+    R: RngCore + CryptoRng,
+{
+    let mut secret_initiator: [u8; 32] = [0u8; 32];
+    rng.fill_bytes(&mut secret_initiator);
+    ed25519::KeyPair::from_secret(secret_initiator, index.unwrap_or(0))
+}
+
+pub fn generate_keypair_x25519() -> (nym_sphinx::PrivateKey, nym_sphinx::PublicKey) {
+    let private_key = nym_sphinx::PrivateKey::random();
+    let public_key = nym_sphinx::PublicKey::from(&private_key);
+    (private_key, public_key)
+}
+
+// (decapsulation_key, encapsulation_key)
+pub fn generate_keypair_libcrux<R>(
+    rng: &mut R,
+    kem: KEM,
+) -> Result<(libcrux_kem::PrivateKey, libcrux_kem::PublicKey), KKTError>
+where
+    R: RngCore + CryptoRng,
+{
+    match kem {
+        KEM::MlKem768 => Ok(key_gen(Algorithm::MlKem768, rng)?),
+        KEM::XWing => Ok(key_gen(Algorithm::XWingKemDraft06, rng)?),
+        KEM::X25519 => Ok(key_gen(Algorithm::X25519, rng)?),
+        _ => Err(KKTError::KEMError {
+            info: "Key Generation Error: Unsupported Libcrux Algorithm",
+        }),
+    }
+}
+// (decapsulation_key, encapsulation_key)
+pub fn generate_keypair_mceliece<'a, R>(
+    rng: &mut R,
+) -> (
+    classic_mceliece_rust::SecretKey<'a>,
+    classic_mceliece_rust::PublicKey<'a>,
+)
+where
+    // this is annoying because mceliece lib uses rand 0.8.5...
+    R: RngCore + CryptoRng,
+{
+    let (encapsulation_key, decapsulation_key) = keypair_boxed(rng);
+    (decapsulation_key, encapsulation_key)
+}
+
+pub fn hash_key_bytes(
+    hash_function: &HashFunction,
+    hash_length: usize,
+    key_bytes: &[u8],
+) -> Vec<u8> {
+    let mut hashed_key: Vec<u8> = vec![0u8; hash_length];
+    match hash_function {
+        HashFunction::Blake3 => {
+            let mut hasher = blake3::Hasher::new();
+            hasher.update(key_bytes);
+            hasher.finalize_xof().fill(&mut hashed_key);
+            hasher.reset();
+        }
+        HashFunction::SHAKE256 => {
+            libcrux_sha3::shake256_ema(&mut hashed_key, key_bytes);
+        }
+        HashFunction::SHAKE128 => {
+            libcrux_sha3::shake128_ema(&mut hashed_key, key_bytes);
+        }
+        HashFunction::SHA256 => {
+            libcrux_sha3::sha256_ema(&mut hashed_key, key_bytes);
+        }
+    }
+
+    hashed_key
+}
+
+/// This does NOT run in constant time.
+// It's fine for KKT since we are comparing hashes.
+fn compare_hashes(a: &[u8], b: &[u8]) -> bool {
+    a == b
+}
+
+pub fn validate_encapsulation_key(
+    hash_function: &HashFunction,
+    hash_length: usize,
+    encapsulation_key: &[u8],
+    expected_hash_bytes: &[u8],
+) -> bool {
+    compare_hashes(
+        &hash_encapsulation_key(hash_function, hash_length, encapsulation_key),
+        expected_hash_bytes,
+    )
+}
+
+pub fn validate_key_bytes(
+    hash_function: &HashFunction,
+    hash_length: usize,
+    key_bytes: &[u8],
+    expected_hash_bytes: &[u8],
+) -> bool {
+    compare_hashes(
+        &hash_key_bytes(hash_function, hash_length, key_bytes),
+        expected_hash_bytes,
+    )
+}
+
+pub fn hash_encapsulation_key(
+    hash_function: &HashFunction,
+    hash_length: usize,
+    encapsulation_key: &[u8],
+) -> Vec<u8> {
+    hash_key_bytes(hash_function, hash_length, encapsulation_key)
+}
@@ -0,0 +1,389 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Convenience wrappers around KKT protocol functions for easier integration.
+//!
+//! This module provides simplified APIs for the common use case of exchanging
+//! KEM public keys between a client (initiator) and gateway (responder).
+//!
+//! The underlying KKT protocol is implemented in the `session` module.
+
+use nym_crypto::asymmetric::ed25519;
+use rand::{CryptoRng, RngCore};
+
+use crate::{
+    ciphersuite::{Ciphersuite, EncapsulationKey},
+    context::{KKTContext, KKTMode},
+    encryption::{decrypt_initial_kkt_frame, decrypt_kkt_frame, encrypt_kkt_frame},
+    error::KKTError,
+};
+
+// Re-export core session functions for advanced use cases
+pub use crate::session::{
+    anonymous_initiator_process, initiator_ingest_response, initiator_process,
+    responder_ingest_message, responder_process,
+};
+
+use crate::encryption::{KKTSessionSecret, encrypt_initial_kkt_frame};
+
+/// Perform an *Encrypted* request for a KEM public key from a responder (OneWay mode).
+///
+/// This is the client-side operation that initiates a KKT exchange.
+/// The request will be signed with the provided signing key.
+///
+/// # Arguments
+/// * `rng` - Random number generator
+/// * `ciphersuite` - Negotiated ciphersuite (KEM, hash, signature algorithms)
+/// * `signing_key` - Client's Ed25519 signing key for authentication
+/// * `responder_dh_public_key` - Responder's long-term x25519 Diffie-Hellman public key
+///
+/// # Returns
+/// * `KKTSessionSecret` - Session Secret Key to use when decrypting responses
+/// * `KKTContext` - Context to use when validating the response
+/// * `Vec<u8>` - Contains the client's ephemeral public key and encrypted and signed bytes to send to responder
+///
+/// # Example
+/// ```ignore
+/// let (session_secret, context, request_frame) = request_kem_key(
+///     &mut rng,
+///     ciphersuite,
+///     client_signing_key,
+///     responder_dh_public_key,
+/// )?;
+/// // Send request_frame to gateway
+/// ```
+pub fn request_kem_key<R: CryptoRng + RngCore>(
+    rng: &mut R,
+    ciphersuite: Ciphersuite,
+    signing_key: &ed25519::PrivateKey,
+    responder_dh_public_key: &nym_sphinx::PublicKey,
+) -> Result<(KKTSessionSecret, KKTContext, Vec<u8>), KKTError> {
+    // OneWay mode: client only wants responder's KEM key
+    // None: client doesn't send their own KEM key
+    let (initiator_context, initiator_frame) =
+        initiator_process(rng, KKTMode::OneWay, ciphersuite, signing_key, None)?;
+
+    // Generate the session's shared secret and encrypt the Intitiator's request
+    let (session_secret, encrypted_request_bytes) =
+        encrypt_initial_kkt_frame(rng, responder_dh_public_key, &initiator_frame)?;
+
+    Ok((session_secret, initiator_context, encrypted_request_bytes))
+}
+
+/// Decrypt, validate an *Encrypted* KKT response and extract the responder's KEM public key.
+///
+/// This is the client-side operation that processes the gateway's response.
+/// It verifies the signature and validates the key hash against the expected value
+/// (typically retrieved from a directory service).
+///
+/// # Arguments
+/// * `context` - Context from the initial request
+/// * `session_secret` - Session Secret Key (generated with request)
+/// * `responder_vk` - Responder's Ed25519 verification key (from directory)
+/// * `expected_key_hash` - Expected hash of responder's KEM key (from directory)
+/// * `response_bytes` - Serialized response frame from responder
+///
+/// # Returns
+/// * `EncapsulationKey` - Authenticated KEM public key of the responder
+///
+/// # Example
+/// ```ignore
+/// let gateway_kem_key = validate_kem_response(
+///     &mut context,
+///     &session_secret,
+///     &gateway_verification_key,
+///     &expected_hash_from_directory,
+///     &response_bytes,
+/// )?;
+/// // Use gateway_kem_key for PSQ
+/// ```
+pub fn validate_kem_response<'a>(
+    context: &mut KKTContext,
+    session_secret: &KKTSessionSecret,
+    responder_vk: &ed25519::PublicKey,
+    expected_key_hash: &[u8],
+    encrypted_response_bytes: &[u8],
+) -> Result<EncapsulationKey<'a>, KKTError> {
+    let (responder_frame, responder_context) =
+        decrypt_kkt_frame(&session_secret, &encrypted_response_bytes, b"KKT_Response")?;
+
+    initiator_ingest_response(
+        context,
+        &responder_frame,
+        &responder_context,
+        responder_vk,
+        &expected_key_hash,
+    )
+}
+
+/// Handle an *Encrypted* KKT request and generate a signed response with the responder's KEM key.
+///
+/// This is the gateway-side operation that processes a client's KKT request.
+/// It validates the request signature (if authenticated) and responds with
+/// the gateway's KEM public key, signed for authenticity.
+///
+/// # Arguments
+/// * `request_frame` - Request frame received from initiator
+/// * `initiator_vk` - Initiator's Ed25519 verification key (None for anonymous)
+/// * `responder_signing_key` - Gateway's Ed25519 signing key
+/// * `responder_kem_key` - Gateway's KEM public key to send
+///
+/// # Returns
+/// * `KKTFrame` - Signed response frame containing the KEM public key
+///
+/// # Example
+/// ```ignore
+/// let response_frame = handle_kem_request(
+///     &request_frame,
+///     Some(client_verification_key),  // or None for anonymous
+///     gateway_signing_key,
+///     &gateway_kem_public_key,
+/// )?;
+/// // Send response_frame back to client
+/// ```
+pub fn handle_kem_request<'a, R>(
+    rng: &mut R,
+    encrypted_request_bytes: &[u8],
+    initiator_vk: Option<&ed25519::PublicKey>,
+    responder_signing_key: &ed25519::PrivateKey,
+    responder_dh_private_key: &nym_sphinx::PrivateKey,
+    responder_kem_key: &EncapsulationKey<'a>,
+) -> Result<Vec<u8>, KKTError>
+where
+    R: RngCore + CryptoRng,
+{
+    // Compute the session's shared secret, decrypt and parse context from the request frame
+
+    let (session_secret, request_frame, initiator_context) =
+        decrypt_initial_kkt_frame(responder_dh_private_key, encrypted_request_bytes)?;
+
+    // Validate the request (verifies signature if initiator_vk provided)
+    let (mut response_context, _) = responder_ingest_message(
+        &initiator_context,
+        initiator_vk,
+        None, // Not checking initiator's KEM key in OneWay mode
+        &request_frame,
+    )?;
+
+    // Generate signed response with our KEM public key
+    let responder_frame = responder_process(
+        &mut response_context,
+        request_frame.session_id_ref(),
+        responder_signing_key,
+        responder_kem_key,
+    )?;
+
+    // Encrypt the responder's response with the session's shared secret
+    encrypt_kkt_frame(rng, &session_secret, &responder_frame, b"KKT_Response")
+}
+
+// #[cfg(test)]
+// mod tests {
+//     use super::*;
+//     use crate::{
+//         ciphersuite::{HashFunction, KEM, SignatureScheme},
+//         key_utils::{generate_keypair_libcrux, hash_encapsulation_key},
+//     };
+
+//     #[test]
+//     fn test_kkt_wrappers_oneway_authenticated() {
+//         let mut rng = rand::rng();
+
+//         // Generate Ed25519 keypairs for both parties
+//         let mut initiator_secret = [0u8; 32];
+//         rng.fill_bytes(&mut initiator_secret);
+//         let initiator_keypair = ed25519::KeyPair::from_secret(initiator_secret, 0);
+
+//         let mut responder_secret = [0u8; 32];
+//         rng.fill_bytes(&mut responder_secret);
+//         let responder_keypair = ed25519::KeyPair::from_secret(responder_secret, 1);
+
+//         // Generate responder's KEM keypair (X25519 for testing)
+//         let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+//         let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+//         // Create ciphersuite
+//         let ciphersuite = Ciphersuite::resolve_ciphersuite(
+//             KEM::X25519,
+//             HashFunction::Blake3,
+//             SignatureScheme::Ed25519,
+//             None,
+//         )
+//         .unwrap();
+
+//         // Hash the KEM key (simulating directory storage)
+//         let key_hash = hash_encapsulation_key(
+//             &ciphersuite.hash_function(),
+//             ciphersuite.hash_len(),
+//             &responder_kem_key.encode(),
+//         );
+
+//         // Client: Request KEM key
+//         let (mut context, request_frame) =
+//             request_kem_key(&mut rng, ciphersuite, initiator_keypair.private_key()).unwrap();
+
+//         // Gateway: Handle request
+//         let response_frame = handle_kem_request(
+//             &request_frame,
+//             Some(initiator_keypair.public_key()), // Authenticated
+//             responder_keypair.private_key(),
+//             &responder_kem_key,
+//         )
+//         .unwrap();
+
+//         // Client: Validate response
+//         let obtained_key = validate_kem_response(
+//             &mut context,
+//             responder_keypair.public_key(),
+//             &key_hash,
+//             &response_frame.to_bytes(),
+//         )
+//         .unwrap();
+
+//         // Verify we got the correct KEM key
+//         assert_eq!(obtained_key.encode(), responder_kem_key.encode());
+//     }
+
+//     #[test]
+//     fn test_kkt_wrappers_anonymous() {
+//         let mut rng = rand::rng();
+
+//         // Only responder has keys
+//         let mut responder_secret = [0u8; 32];
+//         rng.fill_bytes(&mut responder_secret);
+//         let responder_keypair = ed25519::KeyPair::from_secret(responder_secret, 1);
+
+//         let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+//         let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+//         let ciphersuite = Ciphersuite::resolve_ciphersuite(
+//             KEM::X25519,
+//             HashFunction::Blake3,
+//             SignatureScheme::Ed25519,
+//             None,
+//         )
+//         .unwrap();
+
+//         let key_hash = hash_encapsulation_key(
+//             &ciphersuite.hash_function(),
+//             ciphersuite.hash_len(),
+//             &responder_kem_key.encode(),
+//         );
+
+//         // Anonymous initiator
+//         let (mut context, request_frame) =
+//             anonymous_initiator_process(&mut rng, ciphersuite).unwrap();
+
+//         // Gateway: Handle anonymous request
+//         let response_frame = handle_kem_request(
+//             &request_frame,
+//             None, // Anonymous - no verification key
+//             responder_keypair.private_key(),
+//             &responder_kem_key,
+//         )
+//         .unwrap();
+
+//         // Initiator: Validate response
+//         let obtained_key = validate_kem_response(
+//             &mut context,
+//             responder_keypair.public_key(),
+//             &key_hash,
+//             &response_frame.to_bytes(),
+//         )
+//         .unwrap();
+
+//         assert_eq!(obtained_key.encode(), responder_kem_key.encode());
+//     }
+
+//     #[test]
+//     fn test_invalid_signature_rejected() {
+//         let mut rng = rand::rng();
+
+//         let mut initiator_secret = [0u8; 32];
+//         rng.fill_bytes(&mut initiator_secret);
+//         let initiator_keypair = ed25519::KeyPair::from_secret(initiator_secret, 0);
+
+//         let mut responder_secret = [0u8; 32];
+//         rng.fill_bytes(&mut responder_secret);
+//         let responder_keypair = ed25519::KeyPair::from_secret(responder_secret, 1);
+
+//         // Different keypair for wrong signature
+//         let mut wrong_secret = [0u8; 32];
+//         rng.fill_bytes(&mut wrong_secret);
+//         let wrong_keypair = ed25519::KeyPair::from_secret(wrong_secret, 2);
+
+//         let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+//         let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+//         let ciphersuite = Ciphersuite::resolve_ciphersuite(
+//             KEM::X25519,
+//             HashFunction::Blake3,
+//             SignatureScheme::Ed25519,
+//             None,
+//         )
+//         .unwrap();
+
+//         let (_context, request_frame) =
+//             request_kem_key(&mut rng, ciphersuite, initiator_keypair.private_key()).unwrap();
+
+//         // Gateway handles request but we provide WRONG verification key
+//         let result = handle_kem_request(
+//             &request_frame,
+//             Some(wrong_keypair.public_key()), // Wrong key!
+//             responder_keypair.private_key(),
+//             &responder_kem_key,
+//         );
+
+//         // Should fail signature verification
+//         assert!(result.is_err());
+//     }
+
+//     #[test]
+//     fn test_hash_mismatch_rejected() {
+//         let mut rng = rand::rng();
+
+//         let mut initiator_secret = [0u8; 32];
+//         rng.fill_bytes(&mut initiator_secret);
+//         let initiator_keypair = ed25519::KeyPair::from_secret(initiator_secret, 0);
+
+//         let mut responder_secret = [0u8; 32];
+//         rng.fill_bytes(&mut responder_secret);
+//         let responder_keypair = ed25519::KeyPair::from_secret(responder_secret, 1);
+
+//         let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+//         let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+//         let ciphersuite = Ciphersuite::resolve_ciphersuite(
+//             KEM::X25519,
+//             HashFunction::Blake3,
+//             SignatureScheme::Ed25519,
+//             None,
+//         )
+//         .unwrap();
+
+//         // Use WRONG hash
+//         let wrong_hash = [0u8; 32];
+
+//         let (mut context, request_frame) =
+//             request_kem_key(&mut rng, ciphersuite, initiator_keypair.private_key()).unwrap();
+
+//         let response_frame = handle_kem_request(
+//             &request_frame,
+//             Some(initiator_keypair.public_key()),
+//             responder_keypair.private_key(),
+//             &responder_kem_key,
+//         )
+//         .unwrap();
+
+//         // Client validates with WRONG hash
+//         let result = validate_kem_response(
+//             &mut context,
+//             responder_keypair.public_key(),
+//             &wrong_hash, // Wrong!
+//             &response_frame.to_bytes(),
+//         );
+
+//         // Should fail hash validation
+//         assert!(result.is_err());
+//     }
+// }
@@ -0,0 +1,487 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod ciphersuite;
+pub mod context;
+pub mod encryption;
+pub mod error;
+pub mod frame;
+pub mod key_utils;
+pub mod kkt;
+pub mod session;
+
+// This must be less than 4 bits
+pub const KKT_VERSION: u8 = 1;
+const _: () = assert!(KKT_VERSION < 1 << 4);
+
+#[cfg(test)]
+mod test {
+    use nym_crypto::asymmetric::ed25519;
+    use rand::prelude::*;
+
+    use crate::{
+        ciphersuite::{Ciphersuite, EncapsulationKey, HashFunction, KEM},
+        encryption::{
+            decrypt_initial_kkt_frame, decrypt_kkt_frame, encrypt_initial_kkt_frame,
+            encrypt_kkt_frame,
+        },
+        frame::KKTFrame,
+        key_utils::{
+            generate_keypair_ed25519, generate_keypair_libcrux, generate_keypair_mceliece,
+            generate_keypair_x25519, hash_encapsulation_key,
+        },
+        session::{
+            anonymous_initiator_process, initiator_ingest_response, initiator_process,
+            responder_ingest_message, responder_process,
+        },
+    };
+
+    #[test]
+    fn test_kkt_psq_e2e_clear() {
+        let mut rng = rand::rng();
+
+        // generate ed25519 keys
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        for kem in [KEM::MlKem768, KEM::XWing, KEM::X25519, KEM::McEliece] {
+            for hash_function in [
+                HashFunction::Blake3,
+                HashFunction::SHA256,
+                HashFunction::SHAKE128,
+                HashFunction::SHAKE256,
+            ] {
+                let ciphersuite = Ciphersuite::resolve_ciphersuite(
+                    kem,
+                    hash_function,
+                    crate::ciphersuite::SignatureScheme::Ed25519,
+                    None,
+                )
+                .unwrap();
+
+                // generate kem public keys
+
+                let (responder_kem_public_key, initiator_kem_public_key) = match kem {
+                    KEM::MlKem768 => (
+                        EncapsulationKey::MlKem768(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                        EncapsulationKey::MlKem768(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                    ),
+                    KEM::XWing => (
+                        EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                        EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                    ),
+                    KEM::X25519 => (
+                        EncapsulationKey::X25519(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                        EncapsulationKey::X25519(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                    ),
+                    KEM::McEliece => (
+                        EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                        EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                    ),
+                };
+
+                let i_kem_key_bytes = initiator_kem_public_key.encode();
+
+                let r_kem_key_bytes = responder_kem_public_key.encode();
+
+                let i_dir_hash = hash_encapsulation_key(
+                    &ciphersuite.hash_function(),
+                    ciphersuite.hash_len(),
+                    &i_kem_key_bytes,
+                );
+
+                let r_dir_hash = hash_encapsulation_key(
+                    &ciphersuite.hash_function(),
+                    ciphersuite.hash_len(),
+                    &r_kem_key_bytes,
+                );
+
+                // Anonymous Initiator, OneWay
+                {
+                    let (mut i_context, i_frame) =
+                        anonymous_initiator_process(&mut rng, ciphersuite).unwrap();
+
+                    let i_frame_bytes = i_frame.to_bytes();
+
+                    let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                    let (mut r_context, _) =
+                        responder_ingest_message(&r_context, None, None, &i_frame_r).unwrap();
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    let r_bytes = r_frame.to_bytes();
+
+                    let (i_frame_r, i_context_r) = KKTFrame::from_bytes(&r_bytes).unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+                // Initiator, OneWay
+                {
+                    let (mut i_context, i_frame) = initiator_process(
+                        &mut rng,
+                        crate::context::KKTMode::OneWay,
+                        ciphersuite,
+                        initiator_ed25519_keypair.private_key(),
+                        None,
+                    )
+                    .unwrap();
+
+                    let i_frame_bytes = i_frame.to_bytes();
+
+                    let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                    let (mut r_context, r_obtained_key) = responder_ingest_message(
+                        &r_context,
+                        Some(initiator_ed25519_keypair.public_key()),
+                        None,
+                        &i_frame_r,
+                    )
+                    .unwrap();
+
+                    assert!(r_obtained_key.is_none());
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    let r_bytes = r_frame.to_bytes();
+
+                    let (i_frame_r, i_context_r) = KKTFrame::from_bytes(&r_bytes).unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+
+                // Initiator, Mutual
+                {
+                    let (mut i_context, i_frame) = initiator_process(
+                        &mut rng,
+                        crate::context::KKTMode::Mutual,
+                        ciphersuite,
+                        initiator_ed25519_keypair.private_key(),
+                        Some(&initiator_kem_public_key),
+                    )
+                    .unwrap();
+
+                    let i_frame_bytes = i_frame.to_bytes();
+
+                    let (i_frame_r, r_context) = KKTFrame::from_bytes(&i_frame_bytes).unwrap();
+
+                    let (mut r_context, r_obtained_key) = responder_ingest_message(
+                        &r_context,
+                        Some(initiator_ed25519_keypair.public_key()),
+                        Some(&i_dir_hash),
+                        &i_frame_r,
+                    )
+                    .unwrap();
+
+                    assert_eq!(r_obtained_key.unwrap().encode(), i_kem_key_bytes);
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    let r_bytes = r_frame.to_bytes();
+
+                    let (i_frame_r, i_context_r) = KKTFrame::from_bytes(&r_bytes).unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+            }
+        }
+    }
+    #[test]
+    fn test_kkt_psq_e2e_encrypted() {
+        let mut rng = rand::rng();
+
+        // generate ed25519 keys
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        // generate responder x25519 keys
+        let responder_x25519_keypair = generate_keypair_x25519();
+
+        for kem in [KEM::MlKem768, KEM::XWing, KEM::X25519, KEM::McEliece] {
+            for hash_function in [
+                HashFunction::Blake3,
+                HashFunction::SHA256,
+                HashFunction::SHAKE128,
+                HashFunction::SHAKE256,
+            ] {
+                let ciphersuite = Ciphersuite::resolve_ciphersuite(
+                    kem,
+                    hash_function,
+                    crate::ciphersuite::SignatureScheme::Ed25519,
+                    None,
+                )
+                .unwrap();
+
+                // generate kem public keys
+
+                let (responder_kem_public_key, initiator_kem_public_key) = match kem {
+                    KEM::MlKem768 => (
+                        EncapsulationKey::MlKem768(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                        EncapsulationKey::MlKem768(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                    ),
+                    KEM::XWing => (
+                        EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                        EncapsulationKey::XWing(generate_keypair_libcrux(&mut rng, kem).unwrap().1),
+                    ),
+                    KEM::X25519 => (
+                        EncapsulationKey::X25519(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                        EncapsulationKey::X25519(
+                            generate_keypair_libcrux(&mut rng, kem).unwrap().1,
+                        ),
+                    ),
+                    KEM::McEliece => (
+                        EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                        EncapsulationKey::McEliece(generate_keypair_mceliece(&mut rng).1),
+                    ),
+                };
+
+                let i_kem_key_bytes = initiator_kem_public_key.encode();
+
+                let r_kem_key_bytes = responder_kem_public_key.encode();
+
+                let i_dir_hash = hash_encapsulation_key(
+                    &ciphersuite.hash_function(),
+                    ciphersuite.hash_len(),
+                    &i_kem_key_bytes,
+                );
+
+                let r_dir_hash = hash_encapsulation_key(
+                    &ciphersuite.hash_function(),
+                    ciphersuite.hash_len(),
+                    &r_kem_key_bytes,
+                );
+
+                // Anonymous Initiator, OneWay
+                {
+                    let (mut i_context, i_frame) =
+                        anonymous_initiator_process(&mut rng, ciphersuite).unwrap();
+
+                    // encryption - initiator frame
+
+                    let (i_session_secret, i_bytes) =
+                        encrypt_initial_kkt_frame(&mut rng, &responder_x25519_keypair.1, &i_frame)
+                            .unwrap();
+
+                    // decryption - initiator frame
+
+                    let (r_session_secret, i_frame_r, i_context_r) =
+                        decrypt_initial_kkt_frame(&responder_x25519_keypair.0, &i_bytes).unwrap();
+
+                    let (mut r_context, _) =
+                        responder_ingest_message(&i_context_r, None, None, &i_frame_r).unwrap();
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    // encryption - responder frame
+                    let r_bytes =
+                        encrypt_kkt_frame(&mut rng, &r_session_secret, &r_frame, b"KKT_Response")
+                            .unwrap();
+
+                    // decryption - responder frame
+
+                    let (i_frame_r, i_context_r) =
+                        decrypt_kkt_frame(&i_session_secret, &r_bytes, b"KKT_Response").unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+                // Initiator, OneWay
+                {
+                    let (mut i_context, i_frame) = initiator_process(
+                        &mut rng,
+                        crate::context::KKTMode::OneWay,
+                        ciphersuite,
+                        initiator_ed25519_keypair.private_key(),
+                        None,
+                    )
+                    .unwrap();
+
+                    // encryption - initiator frame
+
+                    let (i_session_secret, i_bytes) =
+                        encrypt_initial_kkt_frame(&mut rng, &responder_x25519_keypair.1, &i_frame)
+                            .unwrap();
+
+                    // decryption - initiator frame
+
+                    let (r_session_secret, i_frame_r, r_context) =
+                        decrypt_initial_kkt_frame(&responder_x25519_keypair.0, &i_bytes).unwrap();
+
+                    let (mut r_context, r_obtained_key) = responder_ingest_message(
+                        &r_context,
+                        Some(initiator_ed25519_keypair.public_key()),
+                        None,
+                        &i_frame_r,
+                    )
+                    .unwrap();
+
+                    assert!(r_obtained_key.is_none());
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    // encryption - responder frame
+                    let r_bytes =
+                        encrypt_kkt_frame(&mut rng, &r_session_secret, &r_frame, b"KKT_Response")
+                            .unwrap();
+
+                    // decryption - responder frame
+
+                    let (i_frame_r, i_context_r) =
+                        decrypt_kkt_frame(&i_session_secret, &r_bytes, b"KKT_Response").unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+
+                // Initiator, Mutual
+                {
+                    let (mut i_context, i_frame) = initiator_process(
+                        &mut rng,
+                        crate::context::KKTMode::Mutual,
+                        ciphersuite,
+                        initiator_ed25519_keypair.private_key(),
+                        Some(&initiator_kem_public_key),
+                    )
+                    .unwrap();
+
+                    // encryption - initiator frame
+
+                    let (i_session_secret, i_bytes) =
+                        encrypt_initial_kkt_frame(&mut rng, &responder_x25519_keypair.1, &i_frame)
+                            .unwrap();
+
+                    // decryption - initiator frame
+
+                    let (r_session_secret, i_frame_r, i_context_r) =
+                        decrypt_initial_kkt_frame(&responder_x25519_keypair.0, &i_bytes).unwrap();
+
+                    let (mut r_context, r_obtained_key) = responder_ingest_message(
+                        &i_context_r,
+                        Some(initiator_ed25519_keypair.public_key()),
+                        Some(&i_dir_hash),
+                        &i_frame_r,
+                    )
+                    .unwrap();
+
+                    assert_eq!(r_obtained_key.unwrap().encode(), i_kem_key_bytes);
+
+                    let r_frame = responder_process(
+                        &mut r_context,
+                        i_frame_r.session_id_ref(),
+                        responder_ed25519_keypair.private_key(),
+                        &responder_kem_public_key,
+                    )
+                    .unwrap();
+
+                    // encryption - responder frame
+                    let r_bytes =
+                        encrypt_kkt_frame(&mut rng, &r_session_secret, &r_frame, b"KKT_Response")
+                            .unwrap();
+
+                    // decryption - responder frame
+
+                    let (i_frame_r, i_context_r) =
+                        decrypt_kkt_frame(&i_session_secret, &r_bytes, b"KKT_Response").unwrap();
+
+                    let i_obtained_key = initiator_ingest_response(
+                        &mut i_context,
+                        &i_frame_r,
+                        &i_context_r,
+                        responder_ed25519_keypair.public_key(),
+                        &r_dir_hash,
+                    )
+                    .unwrap();
+
+                    assert_eq!(i_obtained_key.encode(), r_kem_key_bytes)
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,232 @@
+use nym_crypto::asymmetric::ed25519::{self, Signature};
+use rand::{CryptoRng, RngCore};
+
+use crate::{
+    ciphersuite::{Ciphersuite, EncapsulationKey},
+    context::{KKTContext, KKTMode, KKTRole, KKTStatus},
+    error::KKTError,
+    frame::{KKT_SESSION_ID_LEN, KKTFrame},
+    key_utils::validate_encapsulation_key,
+};
+
+pub fn initiator_process<'a, R>(
+    rng: &mut R,
+    mode: KKTMode,
+    ciphersuite: Ciphersuite,
+    signing_key: &ed25519::PrivateKey,
+    own_encapsulation_key: Option<&EncapsulationKey<'a>>,
+) -> Result<(KKTContext, KKTFrame), KKTError>
+where
+    R: CryptoRng + RngCore,
+{
+    let context = KKTContext::new(KKTRole::Initiator, mode, ciphersuite)?;
+
+    let context_bytes = context.encode()?;
+
+    let mut session_id = [0; KKT_SESSION_ID_LEN];
+    // Generate Session ID
+    rng.fill_bytes(&mut session_id);
+
+    let body: &[u8] = match mode {
+        KKTMode::OneWay => &[],
+        KKTMode::Mutual => match own_encapsulation_key {
+            Some(encaps_key) => &encaps_key.encode(),
+
+            // Missing key
+            None => {
+                return Err(KKTError::FunctionInputError {
+                    info: "KEM Key Not Provided",
+                });
+            }
+        },
+    };
+
+    let mut bytes_to_sign =
+        Vec::with_capacity(context.full_message_len() - context.signature_len());
+    bytes_to_sign.extend_from_slice(&context_bytes);
+    bytes_to_sign.extend_from_slice(body);
+    bytes_to_sign.extend_from_slice(&session_id);
+
+    let signature = signing_key.sign(bytes_to_sign).to_bytes();
+
+    Ok((
+        context,
+        KKTFrame::new(&context_bytes, body, &session_id, &signature),
+    ))
+}
+
+pub fn anonymous_initiator_process<R>(
+    rng: &mut R,
+    ciphersuite: Ciphersuite,
+) -> Result<(KKTContext, KKTFrame), KKTError>
+where
+    R: CryptoRng + RngCore,
+{
+    let context = KKTContext::new(KKTRole::AnonymousInitiator, KKTMode::OneWay, ciphersuite)?;
+    let context_bytes = context.encode()?;
+
+    let mut session_id = [0u8; KKT_SESSION_ID_LEN];
+    rng.fill_bytes(&mut session_id);
+
+    Ok((
+        context,
+        KKTFrame::new(&context_bytes, &[], &session_id, &[]),
+    ))
+}
+
+pub fn initiator_ingest_response<'a>(
+    own_context: &mut KKTContext,
+    remote_frame: &KKTFrame,
+    remote_context: &KKTContext,
+    remote_verification_key: &ed25519::PublicKey,
+    expected_hash: &[u8],
+) -> Result<EncapsulationKey<'a>, KKTError> {
+    check_compatibility(own_context, &remote_context)?;
+    match remote_context.status() {
+        KKTStatus::Ok => {
+            let mut bytes_to_verify: Vec<u8> = Vec::with_capacity(
+                remote_context.full_message_len() - remote_context.signature_len(),
+            );
+            bytes_to_verify.extend_from_slice(&remote_context.encode()?);
+            bytes_to_verify.extend_from_slice(remote_frame.body_ref());
+            bytes_to_verify.extend_from_slice(remote_frame.session_id_ref());
+
+            match Signature::from_bytes(remote_frame.signature_ref()) {
+                Ok(sig) => match remote_verification_key.verify(bytes_to_verify, &sig) {
+                    Ok(()) => {
+                        let received_encapsulation_key = EncapsulationKey::decode(
+                            own_context.ciphersuite().kem(),
+                            remote_frame.body_ref(),
+                        )?;
+
+                        match validate_encapsulation_key(
+                            &own_context.ciphersuite().hash_function(),
+                            own_context.ciphersuite().hash_len(),
+                            remote_frame.body_ref(),
+                            expected_hash,
+                        ) {
+                            true => Ok(received_encapsulation_key),
+
+                            // The key does not match the hash obtained from the directory
+                            false => Err(KKTError::KEMError {
+                                info: "Hash of received encapsulation key does not match the value stored on the directory.",
+                            }),
+                        }
+                    }
+                    Err(_) => Err(KKTError::SigVerifError),
+                },
+                Err(_) => Err(KKTError::SigConstructorError),
+            }
+        }
+        _ => Err(KKTError::ResponderFlaggedError {
+            status: remote_context.status(),
+        }),
+    }
+}
+
+// todo: figure out how to handle errors using status codes
+
+pub fn responder_ingest_message<'a>(
+    remote_context: &KKTContext,
+    remote_verification_key: Option<&ed25519::PublicKey>,
+    expected_hash: Option<&[u8]>,
+    remote_frame: &KKTFrame,
+) -> Result<(KKTContext, Option<EncapsulationKey<'a>>), KKTError> {
+    let own_context = remote_context.derive_responder_header()?;
+
+    match remote_context.role() {
+        KKTRole::AnonymousInitiator => Ok((own_context, None)),
+
+        KKTRole::Initiator => {
+            match remote_verification_key {
+                Some(remote_verif_key) => {
+                    let mut bytes_to_verify: Vec<u8> = Vec::with_capacity(
+                        own_context.full_message_len() - own_context.signature_len(),
+                    );
+                    bytes_to_verify.extend_from_slice(remote_frame.context_ref());
+                    bytes_to_verify.extend_from_slice(remote_frame.body_ref());
+                    bytes_to_verify.extend_from_slice(remote_frame.session_id_ref());
+
+                    match Signature::from_bytes(remote_frame.signature_ref()) {
+                        Ok(sig) => match remote_verif_key.verify(bytes_to_verify, &sig) {
+                            Ok(()) => {
+                                // using own_context here because maybe for whatever reason we want to ignore the remote kem key
+                                match own_context.mode() {
+                                    KKTMode::OneWay => Ok((own_context, None)),
+                                    KKTMode::Mutual => {
+                                        match expected_hash {
+                                            Some(expected_hash) => {
+                                                let received_encapsulation_key =
+                                                    EncapsulationKey::decode(
+                                                        own_context.ciphersuite().kem(),
+                                                        remote_frame.body_ref(),
+                                                    )?;
+                                                if validate_encapsulation_key(
+                                                    &own_context.ciphersuite().hash_function(),
+                                                    own_context.ciphersuite().hash_len(),
+                                                    remote_frame.body_ref(),
+                                                    expected_hash,
+                                                ) {
+                                                    Ok((
+                                                        own_context,
+                                                        Some(received_encapsulation_key),
+                                                    ))
+                                                }
+                                                // The key does not match the hash obtained from the directory
+                                                else {
+                                                    Err(KKTError::KEMError {
+                                                        info: "Hash of received encapsulation key does not match the value stored on the directory.",
+                                                    })
+                                                }
+                                            }
+                                            None => Err(KKTError::FunctionInputError {
+                                                info: "Expected hash of the remote encapsulation key is not provided.",
+                                            }),
+                                        }
+                                    }
+                                }
+                            }
+                            Err(_) => Err(KKTError::SigVerifError),
+                        },
+                        Err(_) => Err(KKTError::SigConstructorError),
+                    }
+                }
+                None => Err(KKTError::FunctionInputError {
+                    info: "Remote Signature Verification Key Not Provided",
+                }),
+            }
+        }
+        KKTRole::Responder => Err(KKTError::IncompatibilityError {
+            info: "Responder received a request from another responder.",
+        }),
+    }
+}
+
+pub fn responder_process<'a>(
+    own_context: &mut KKTContext,
+    session_id: &[u8],
+    signing_key: &ed25519::PrivateKey,
+    encapsulation_key: &EncapsulationKey<'a>,
+) -> Result<KKTFrame, KKTError> {
+    let body = encapsulation_key.encode();
+
+    let context_bytes = own_context.encode()?;
+
+    let mut bytes_to_sign =
+        Vec::with_capacity(own_context.full_message_len() - own_context.signature_len());
+    bytes_to_sign.extend_from_slice(&own_context.encode()?);
+    bytes_to_sign.extend_from_slice(&body);
+    bytes_to_sign.extend_from_slice(session_id);
+
+    let signature = signing_key.sign(bytes_to_sign).to_bytes();
+
+    Ok(KKTFrame::new(&context_bytes, &body, session_id, &signature))
+}
+
+fn check_compatibility(
+    _own_context: &KKTContext,
+    _remote_context: &KKTContext,
+) -> Result<(), KKTError> {
+    // todo: check ciphersuite/context compatibility
+    Ok(())
+}
@@ -0,0 +1,7 @@
+[package]
+name = "nym-lp-common"
+version = "0.1.0"
+edition = { workspace = true }
+license = { workspace = true }
+
+[dependencies]
@@ -0,0 +1,28 @@
+use std::fmt;
+use std::fmt::Write;
+
+pub fn format_debug_bytes(bytes: &[u8]) -> Result<String, fmt::Error> {
+    let mut out = String::new();
+    const LINE_LEN: usize = 16;
+    for (i, chunk) in bytes.chunks(LINE_LEN).enumerate() {
+        let line_prefix = format!("[{}:{}]", 1 + i * LINE_LEN, i * LINE_LEN + chunk.len());
+        write!(out, "{line_prefix:12}")?;
+        let mut line = String::new();
+        for b in chunk {
+            line.push_str(format!("{:02x} ", b).as_str());
+        }
+        write!(
+            out,
+            "{line:48} {}",
+            chunk
+                .iter()
+                .map(|&b| b as char)
+                .map(|c| if c.is_alphanumeric() { c } else { '.' })
+                .collect::<String>()
+        )?;
+
+        writeln!(out)?;
+    }
+
+    Ok(out)
+}
@@ -0,0 +1,47 @@
+[package]
+name = "nym-lp"
+version = "0.1.0"
+edition = { workspace = true }
+license = { workspace = true }
+
+[dependencies]
+bincode = { workspace = true }
+thiserror = { workspace = true }
+parking_lot = { workspace = true }
+snow = { workspace = true }
+bs58 = { workspace = true }
+serde = { workspace = true }
+bytes = { workspace = true }
+dashmap = { workspace = true }
+sha2 = { workspace = true }
+ansi_term = { workspace = true }
+tracing = { workspace = true }
+utoipa = { workspace = true, features = ["macros", "non_strict_integers"] }
+rand = { workspace = true }
+# rand 0.9 for KKT integration (nym-kkt uses rand 0.9)
+rand09 = { package = "rand", version = "0.9.2" }
+
+nym-crypto = { path = "../crypto", features = ["hashing", "asymmetric"] }
+nym-kkt = { path = "../nym-kkt" }
+nym-lp-common = { path = "../nym-lp-common" }
+nym-sphinx = { path = "../nymsphinx" }
+
+# libcrux dependencies for PSQ (Post-Quantum PSK derivation)
+libcrux-psq = { git = "https://github.com/cryspen/libcrux", features = [
+    "test-utils",
+] }
+libcrux-kem = { git = "https://github.com/cryspen/libcrux" }
+libcrux-traits = { git = "https://github.com/cryspen/libcrux" }
+tls_codec = { workspace = true }
+num_enum = { workspace = true }
+chacha20poly1305 = { workspace = true }
+zeroize = { workspace = true, features = ["zeroize_derive"] }
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+rand_chacha = "0.3"
+
+
+[[bench]]
+name = "replay_protection"
+harness = false
@@ -0,0 +1,365 @@
+# LP Protocol Design
+
+## Overview
+
+The Lewes Protocol (LP) provides authenticated, encrypted sessions with replay protection. Key design principles:
+
+1. **Unified packet structure** - Same format for all packet types
+2. **Receiver index** - Client-proposed session identifier (replaces computed session_id)
+3. **Opportunistic encryption** - Header authentication and payload encryption as soon as PSK is available
+4. **WireGuard-inspired simplicity** - Minimal header, clear security model
+
+## Packet Structure
+
+### Unified Format (v2)
+
+All packets share the same outer structure - cleartext fields are always first:
+
+```
+┌────────────────┬─────────┬─────────┬──────────┬─────────────────────┬─────────┐
+│ receiver_index │ counter │ version │ reserved │ payload             │ trailer │
+│ 4B             │ 8B      │ 1B      │ 3B       │ variable            │ 16B     │
+└────────────────┴─────────┴─────────┴──────────┴─────────────────────┴─────────┘
+│←── 12B outer header ────┤│←── inner (cleartext or encrypted) ──────┤│─ 16B ──┤
+```
+
+**Total overhead:** 32 bytes (12B outer + 4B inner prefix + 16B trailer)
+
+Key properties:
+- **Outer header** (12 bytes): Always cleartext, used for routing before session lookup
+- **Inner content**: Cleartext before PSK, encrypted after PSK
+- **No disambiguation needed**: Format is identical for both modes
+
+### Field Descriptions
+
+**Outer Header** (always cleartext, 12 bytes):
+
+| Field | Size | Description |
+|-------|------|-------------|
+| receiver_index | 4 bytes | Session identifier, proposed by client (routing key) |
+| counter | 8 bytes | Monotonic counter, used as AEAD nonce and for replay protection |
+
+**Inner Content** (cleartext or encrypted):
+
+| Field | Size | Description |
+|-------|------|-------------|
+| version | 1 byte | Protocol version |
+| reserved | 3 bytes | Reserved for future use |
+| payload | variable | Message type (2B) + content |
+| trailer | 16 bytes | Zeros (no PSK) or AEAD Poly1305 tag (with PSK) |
+
+### Wire Format
+
+Length-prefixed over TCP:
+
+```
+┌────────────────────┬─────────────────────────────────────────────────────┐
+│ length (4B BE u32) │ LpPacket                                            │
+└────────────────────┴─────────────────────────────────────────────────────┘
+```
+
+## Message Types
+
+| Type | Value | Description |
+|------|-------|-------------|
+| Busy | 0x0000 | Server congestion signal |
+| Handshake | 0x0001 | Noise protocol messages |
+| EncryptedData | 0x0002 | Encrypted application data |
+| ClientHello | 0x0003 | Initial session setup |
+| KKTRequest | 0x0004 | KEM key transfer request |
+| KKTResponse | 0x0005 | KEM key transfer response |
+| ForwardPacket | 0x0006 | Nested session forwarding |
+| Collision | 0x0007 | Receiver index collision |
+| Ack | 0x0008 | Gateway confirms receipt of message |
+
+### Planned Message Types (not yet implemented)
+
+| Type | Value | Description |
+|------|-------|-------------|
+| SubsessionRequest | 0x0009 | Client requests new subsession |
+| SubsessionKK1 | 0x000A | KK handshake msg 1 (responder → initiator) |
+| SubsessionKK2 | 0x000B | KK handshake msg 2 (initiator → responder) |
+| SubsessionReady | 0x000C | Subsession established confirmation |
+
+## Receiver Index
+
+### Assignment
+
+The client generates a random 4-byte receiver_index and includes it in ClientHello. The gateway uses this as the session lookup key. This replaces the previous approach of computing a deterministic session_id from both parties' keys.
+
+### Collision Handling
+
+With 4 bytes (2^32 values), collision probability is negligible:
+
+| Active Sessions | Collision Probability |
+|-----------------|----------------------|
+| 10,000 | ~0.001% |
+| 100,000 | ~0.1% |
+
+If collision detected, gateway rejects ClientHello and client retries with new index.
+
+## Opportunistic Encryption
+
+### Principle
+
+As soon as PSK is derived (after processing Noise msg 1 with PSQ), all subsequent packets use outer AEAD encryption:
+
+- **Header**: Authenticated as associated data (AD)
+- **Payload**: Encrypted (message type + content)
+- **Trailer**: AEAD tag
+
+### Timeline
+
+| Packet | PSK Available | Header | Payload | Trailer |
+|--------|---------------|--------|---------|---------|
+| ClientHello | No | Clear | Clear | Zeros |
+| Ack | No | Clear | Clear | Zeros |
+| KKTRequest | No | Clear | Clear | Zeros |
+| KKTResponse | No | Clear | Clear | Zeros |
+| Noise msg 1 | No | Clear | Clear | Zeros |
+| | | **PSK derived** | | |
+| Noise msg 2 | Yes | Authenticated | Encrypted | Tag |
+| Noise msg 3 | Yes | Authenticated | Encrypted | Tag |
+| Data | Yes | Authenticated | Encrypted | Tag |
+
+### Encryption Scheme
+
+- **AEAD**: ChaCha20-Poly1305
+- **Key**: outer_key = KDF(PSK, "lp-outer-aead") - derived from PSK, not PSK itself
+- **Nonce**: counter (8 bytes, zero-padded to 12 bytes)
+- **AAD**: receiver_index ‖ counter (12 bytes) - the outer header
+- **Encrypted**: version ‖ reserved ‖ message_type ‖ content
+
+Note: PSK is used as-is for Noise (which does internal key derivation). The outer_key derivation avoids key reuse between the two encryption layers.
+
+### Before PSK
+
+```
+┌────────────────┬─────────┬─────────┬──────────┬─────────────────────┬─────────┐
+│ receiver_index │ counter │ version │ reserved │ payload             │ 00...00 │
+│                │         │         │          │ (plaintext)         │         │
+└────────────────┴─────────┴─────────┴──────────┴─────────────────────┴─────────┘
+│←── 12B outer ──────────┤│←────────────── cleartext inner ──────────┤│─zeros──┤
+```
+
+### After PSK
+
+```
+┌────────────────┬─────────┬─────────┬──────────┬─────────────────────┬─────────┐
+│ receiver_index │ counter │ version │ reserved │ payload             │ tag     │
+│                │         │ (enc)   │ (enc)    │ (encrypted)         │         │
+└────────────────┴─────────┴─────────┴──────────┴─────────────────────┴─────────┘
+│←── 12B outer (AAD) ────┤│←────────── encrypted inner ──────────────┤│─ tag ──┤
+```
+
+## Handshake Flow
+
+Each arrow represents a separate TCP connection (packet-per-connection model).
+
+```
+Client                                  Gateway
+   │                                       │
+   │ [hdr][ClientHello][zeros]             │
+   │──────────────────────────────────────►│ store state[receiver_index]
+   │                                       │
+   │ [hdr][Ack][zeros]                     │
+   │◄──────────────────────────────────────│ confirm ClientHello
+   │                                       │
+   │ [hdr][KKTRequest][zeros]              │
+   │──────────────────────────────────────►│
+   │                                       │
+   │ [hdr][KKTResponse][zeros]             │
+   │◄──────────────────────────────────────│
+   │                                       │
+   │ [hdr][Noise1+PSQ][zeros]              │
+   │──────────────────────────────────────►│ derive PSK
+   │                                       │
+   │ [hdr][encrypted Noise2][tag]          │ ← authenticated
+   │◄──────────────────────────────────────│
+   │                                       │
+   │ [hdr][encrypted Noise3][tag]          │ ← authenticated
+   │──────────────────────────────────────►│
+   │                                       │
+   │ ════════ Session Established ═════════│
+   │                                       │
+   │ [hdr][encrypted Data][tag]            │
+   │◄─────────────────────────────────────►│
+```
+
+## Data Packet Encryption
+
+Data packets have two encryption layers:
+
+```
+Application Data
+       │
+       ▼
+┌─────────────────────┐
+│ Noise encrypt       │  Inner layer (forward secrecy, ratcheting)
+│ (session keys)      │
+└─────────────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│ PSK AEAD            │  Outer layer (header auth, payload encryption)
+│ (pre-shared key)    │
+└─────────────────────┘
+       │
+       ▼
+Wire: [header][encrypted payload][tag]
+```
+
+### What Outer AEAD Encrypts
+
+The outer AEAD encrypts: message_type (2B) + message content
+
+This hides the message type from observers after PSK is available.
+
+## Subsessions and Rekeying
+
+Subsessions enable **forward secrecy** through periodic rekeying and **channel multiplexing** for independent encrypted streams.
+
+### Design Principles
+
+| Aspect | Decision | Rationale |
+|--------|----------|-----------|
+| Key derivation | Noise KK handshake | Clean crypto, both parties already authenticated |
+| Initiation channel | Tunneled through parent | Already authenticated, no proof-of-ownership needed |
+| Hierarchy | Promotion model (chain) | Simpler than tree, natural for rekeying |
+| Old session after promotion | Read-only until TTL | Drains in-flight packets, provides grace period |
+
+### Noise KK Pattern
+
+Subsessions use `Noise_KK_25519_ChaChaPoly_SHA256`:
+
+- **KK** = Both parties already know each other's static keys
+- **2 messages** to complete (vs 3 for XKpsk3)
+- **No PSK needed** - already authenticated via parent session
+
+### Promotion Model
+
+When a subsession is created, it becomes the new "master" and the old session becomes read-only:
+
+```
+Session A (master) → Session B created → A demoted, B is master
+                                         A: read-only until TTL
+```
+
+This creates a chain (A → B → C) but maintains only one level of nesting conceptually. Each promotion replaces the previous master.
+
+### Protocol Flow
+
+```
+Client                              Gateway
+  │                                   │
+  │═══════ Parent Session (A) ════════│  Transport mode
+  │                                   │
+  │──[SubsessionRequest{idx=B}]──────►│  Encrypted in parent
+  │                                   │  Gateway creates KK responder
+  │◄──[SubsessionKK1{idx=B, e}]───────│  KK handshake msg 1
+  │──[SubsessionKK2{idx=B, e,ee,se}]─►│  KK handshake msg 2
+  │◄──[SubsessionReady{idx=B}]────────│  Subsession established
+  │                                   │
+  │  Session A: read-only (receive)   │
+  │═══════ Session B (new master) ════│  New Transport mode
+```
+
+### Session State Transitions
+
+```
+Parent Session (A):
+  Transport → ReadOnlyTransport (on subsession creation)
+  ReadOnlyTransport → (expires via TTL cleanup)
+
+Subsession (B):
+  (created) → KKHandshaking → Transport (becomes new master)
+```
+
+### Read-Only Session Semantics
+
+After demotion:
+- **Can receive**: Decrypt and process incoming packets (drain in-flight)
+- **Cannot send**: Encryption blocked, returns error
+- **Cleaned up**: Via normal TTL expiration
+
+### Message Formats
+
+```rust
+SubsessionRequestData {
+    new_receiver_index: u32,  // Client-proposed index for subsession
+}
+
+SubsessionKK1Data {
+    new_receiver_index: u32,
+    kk_message: Vec<u8>,      // Noise KK message 1
+}
+
+SubsessionKK2Data {
+    new_receiver_index: u32,
+    kk_message: Vec<u8>,      // Noise KK message 2
+}
+
+SubsessionReadyData {
+    new_receiver_index: u32,
+}
+```
+
+### Counter Independence
+
+- Each session has independent counters
+- Subsession starts at counter 0
+- No counter coordination needed between parent and subsession
+
+### Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| KK handshake fails | Discard attempt, keep using parent |
+| Receiver index collision | Retry with new receiver_index |
+| Parent session not found | Return error, client reconnects |
+
+### Security Benefits
+
+1. **Forward secrecy**: Compromise of current keys doesn't expose past traffic
+2. **Key rotation**: Periodic rekeying limits exposure window
+3. **Channel isolation**: Independent streams can't cross-decrypt
+
+## Security Properties
+
+### Always Visible to Observer
+
+Only the outer header (12 bytes) is visible after PSK establishment:
+
+- Receiver index (4 bytes) - opaque, unlinkable to identity
+- Counter (8 bytes) - reveals packet ordering
+- Packet size
+
+Note: Before PSK, version, reserved, and message type are also visible.
+
+### Protected After PSK
+
+- Outer header integrity (authenticated via AEAD AAD)
+- Inner content confidentiality (encrypted):
+  - Protocol version
+  - Reserved field
+  - Message type
+  - Payload
+- Application data (double encrypted: outer AEAD + inner Noise)
+
+### Cryptographic Guarantees
+
+| Property | Mechanism |
+|----------|-----------|
+| Confidentiality | ChaCha20 (outer) + Noise ChaCha20 (inner) |
+| Integrity | Poly1305 (outer) + Noise Poly1305 (inner) |
+| Replay protection | Counter validation (before decryption) |
+| Forward secrecy | Noise session keys (inner) + subsession rekeying |
+| Header authentication | AEAD associated data |
+| Key rotation | Periodic subsession creation (Noise KK) |
+
+## References
+
+- WireGuard Protocol - Inspiration for receiver_index and packet simplicity
+- Noise Protocol Framework - Inner encryption layer, KK pattern for subsessions
+- RFC 8439 ChaCha20-Poly1305 - AEAD cipher
+- Noise Explorer KK - https://noiseexplorer.com/patterns/KK/
@@ -0,0 +1,309 @@
+# Nym Lewes Protocol
+
+The Lewes Protocol (LP) is a secure network communication protocol implemented in Rust. It provides authenticated, encrypted sessions with replay protection and supports nested session forwarding for privacy-preserving multi-hop connections.
+
+## Architecture Overview
+
+```
+┌─────────────────┐     ┌────────────────┐     ┌───────────────┐
+│ Transport Layer │◄───►│ LP Session     │◄───►│ LP Codec      │
+│ (TCP)           │     │ - State machine│     │ - Serialize   │
+└─────────────────┘     │ - Noise crypto │     │ - Deserialize │
+                        │ - Replay prot. │     └───────────────┘
+                        └────────────────┘
+```
+
+## Packet Structure
+
+The protocol uses a length-prefixed packet format over TCP:
+
+```
+Wire Format:
+┌────────────────────┬─────────────────────────────────────────┐
+│ Length (4B BE u32) │ LpPacket                                │
+└────────────────────┴─────────────────────────────────────────┘
+
+LpPacket:
+┌──────────────────┬───────────────────┬──────────────────┐
+│ Header (16B)     │ Message           │ Trailer (16B)    │
+├──────────────────┼───────────────────┼──────────────────┤
+│ Version (1B)     │ Type (2B LE u16)  │ Reserved         │
+│ Reserved (3B)    │ Content (var)     │ (16 bytes)       │
+│ SessionID (4B LE)│                   │                  │
+│ Counter (8B LE)  │                   │                  │
+└──────────────────┴───────────────────┴──────────────────┘
+```
+
+- **Header**: Protocol version (1), session identifier, monotonic counter
+- **Message**: Type discriminant + variable-length content
+- **Trailer**: Reserved for future use (16 bytes)
+
+## Message Types
+
+| Type | Value | Purpose |
+|------|-------|---------|
+| `Busy` | 0x0000 | Server congestion signal |
+| `Handshake` | 0x0001 | Noise protocol handshake messages |
+| `EncryptedData` | 0x0002 | Encrypted application data |
+| `ClientHello` | 0x0003 | Initial session negotiation |
+| `KKTRequest` | 0x0004 | KEM Key Transfer request |
+| `KKTResponse` | 0x0005 | KEM Key Transfer response |
+| `ForwardPacket` | 0x0006 | Nested session forwarding |
+
+## Session Establishment
+
+### Session ID
+
+Sessions are identified by a deterministic 32-bit ID computed from both parties' X25519 public keys:
+
+```
+session_id = make_lp_id(client_x25519_pub, gateway_x25519_pub)
+```
+
+The computation is order-independent, allowing both sides to derive the same ID independently.
+
+**BOOTSTRAP_SESSION_ID (0)**: A special session ID used only for the initial `ClientHello` packet, since neither side can compute the final ID until both X25519 keys are known.
+
+### Handshake Flow
+
+```
+┌────────┐                              ┌─────────┐
+│ Client │                              │ Gateway │
+└───┬────┘                              └────┬────┘
+    │                                        │
+    │ 1. ClientHello (session_id=0)          │
+    │   [client_x25519, client_ed25519, salt]│
+    │───────────────────────────────────────►│
+    │                                        │ (computes session_id)
+    │                                        │ (stores state machine)
+    │                                        │
+    │ 2. KKTRequest (session_id=N)           │
+    │   [signed request for KEM key]         │
+    │───────────────────────────────────────►│
+    │                                        │
+    │ 3. KKTResponse                         │
+    │   [gateway KEM key + signature]        │
+    │◄───────────────────────────────────────│
+    │                                        │
+    │ 4. Noise Handshake Msg 1               │
+    │   [PSQ payload + noise message]        │
+    │───────────────────────────────────────►│
+    │                                        │ (derives PSK from PSQ)
+    │ 5. Noise Handshake Msg 2               │
+    │   [PSK handle + noise message]         │
+    │◄───────────────────────────────────────│
+    │                                        │
+    │ 6. Noise Handshake Msg 3               │
+    │───────────────────────────────────────►│
+    │                                        │
+    │ ═══════ Session Established ═══════    │
+    │                                        │
+    │ 7. EncryptedData                       │
+    │   [encrypted application data]         │
+    │◄──────────────────────────────────────►│
+    │                                        │
+```
+
+### ClientHello Data
+
+```rust
+struct ClientHelloData {
+    client_lp_public_key: [u8; 32],      // X25519 (derived from Ed25519)
+    client_ed25519_public_key: [u8; 32], // For authentication
+    salt: [u8; 32],                       // timestamp (8B) + nonce (24B)
+}
+```
+
+## Packet-Per-Connection Model
+
+The gateway processes **exactly one packet per TCP connection**, then closes. State persists between connections via in-memory maps:
+
+```
+TCP Connect → Receive Packet → Process → Send Response → TCP Close
+```
+
+**State Storage:**
+- `handshake_states`: Maps `session_id → LpStateMachine` (during handshake)
+- `session_states`: Maps `session_id → LpSession` (after handshake complete)
+
+Both maps use TTL-based cleanup to remove stale entries (default: 5 min handshake, 1 hour session).
+
+### Gateway Packet Routing
+
+```
+Packet Received
+    │
+    ├─► session_id == 0 (BOOTSTRAP)
+    │   └─► handle_client_hello()
+    │       └─► Create state machine, store in handshake_states
+    │
+    ├─► session_id in handshake_states
+    │   └─► handle_handshake_packet()
+    │       └─► Process KKT/Noise, move to session_states when complete
+    │
+    └─► session_id in session_states
+        └─► handle_transport_packet()
+            └─► Decrypt, process registration or forwarding
+```
+
+## Session Forwarding
+
+Forwarding enables a client to establish an independent session with an exit gateway through an entry gateway, providing network-level privacy.
+
+### Architecture
+
+```
+┌──────────┐
+│  Client  │
+└────┬─────┘
+     │ Outer LP Session (established, encrypted)
+     │
+     ▼
+┌────────────────┐
+│ Entry Gateway  │  Sees: Client IP
+│                │  Doesn't see: Exit destination
+└────────┬───────┘
+         │ Forwards inner packets (TCP)
+         │
+         ▼
+┌────────────────┐
+│ Exit Gateway   │  Sees: Entry Gateway IP
+│                │  Doesn't see: Client IP
+└────────────────┘
+```
+
+### ForwardPacket Message
+
+```rust
+struct ForwardPacketData {
+    target_gateway_identity: [u8; 32], // Exit gateway's Ed25519 key
+    target_lp_address: String,          // e.g., "2.2.2.2:41264"
+    inner_packet_bytes: Vec<u8>,        // Complete LP packet for exit
+}
+```
+
+### Forwarding Flow
+
+1. **Client** establishes outer LP session with entry gateway
+2. **Client** creates `ClientHello` packet for exit gateway
+3. **Client** wraps inner packet in `ForwardPacketData`:
+   - Sets `target_gateway_identity` to exit's Ed25519 key
+   - Sets `target_lp_address` to exit's LP listener address
+   - Serializes complete LP packet as `inner_packet_bytes`
+4. **Client** encrypts `ForwardPacketData` using outer session
+5. **Client** sends as `EncryptedData` to entry gateway
+
+6. **Entry Gateway** decrypts, sees `ForwardPacketData`
+7. **Entry Gateway** connects to exit gateway (new TCP)
+8. **Entry Gateway** sends `inner_packet_bytes` directly
+9. **Entry Gateway** receives exit's response
+10. **Entry Gateway** encrypts response using outer session
+11. **Entry Gateway** sends encrypted response to client
+
+12. **Client** decrypts response, processes in inner session state
+
+### NestedLpSession
+
+The `NestedLpSession` struct manages the inner session from the client's perspective:
+
+```rust
+struct NestedLpSession {
+    exit_identity: [u8; 32],           // Exit gateway Ed25519
+    exit_address: String,               // Exit LP address
+    client_keypair: Arc<ed25519::KeyPair>,
+    exit_public_key: ed25519::PublicKey,
+    state_machine: Option<LpStateMachine>,
+}
+```
+
+**Usage:**
+```rust
+// Create nested session targeting exit gateway
+let nested = NestedLpSession::new(exit_identity, exit_address, keypair, exit_pubkey);
+
+// Perform handshake through outer session
+nested.handshake_and_register(&mut outer_client).await?;
+
+// Inner session now established with exit gateway
+```
+
+## State Machine States
+
+```
+ReadyToHandshake
+       │
+       ▼
+   KKTExchange ◄─── KKTRequest/KKTResponse
+       │
+       ▼
+   Handshaking ◄─── Noise messages + PSQ
+       │
+       ▼
+    Transport ◄─── EncryptedData
+       │
+       ▼
+     Closed
+```
+
+## Cryptography
+
+### Key Types
+- **Ed25519**: Identity keys, signing
+- **X25519**: Key exchange (derived from Ed25519 via RFC 7748)
+
+### Noise Protocol
+- Pattern: `Noise_XKpsk3_25519_ChaChaPoly_SHA256`
+- Provides: Forward secrecy, mutual authentication, PSK binding
+
+### PSK Derivation (PSQ)
+The Pre-Shared Key is derived via Post-Quantum Secure Key Exchange:
+1. Client encapsulates using authenticated KEM key from KKT
+2. Produces 32-byte PSK + ciphertext
+3. Gateway decapsulates to derive same PSK
+4. PSK injected into Noise at position 3
+
+### Replay Protection
+
+- **Monotonic counter**: Each packet has incrementing 64-bit counter
+- **Sliding window**: Bitmap tracks received counters (1024 packet window)
+- **SIMD optimized**: Branchless validation for constant-time operation
+
+```rust
+// Validation flow
+validator.will_accept_branchless(counter) // Check before decrypt
+validator.mark_did_receive_branchless(counter) // Mark after decrypt
+```
+
+## Sessions
+
+### LpSession Fields
+```rust
+struct LpSession {
+    id: u32,                    // Session identifier
+    is_initiator: bool,         // Client or gateway role
+    noise_state: NoiseState,    // Noise transport state
+    kkt_state: KktState,        // KKT exchange progress
+    psq_state: PsqState,        // PSQ handshake progress
+    psk_handle: Option<Vec<u8>>,// PSK handle from responder
+    sending_counter: AtomicU64, // Outgoing packet counter
+    receiving_counter: Validator, // Replay protection
+    psk_injected: AtomicBool,   // Safety: real PSK injected?
+}
+```
+
+### PSK Safety
+Sessions initialize with a dummy PSK. The `psk_injected` flag must be `true` before `encrypt_data()` or `decrypt_data()` will operate, preventing accidental use of the insecure dummy.
+
+## File Structure
+
+```
+common/nym-lp/src/
+├── lib.rs           # Module exports
+├── message.rs       # LpMessage enum, ClientHelloData, ForwardPacketData
+├── packet.rs        # LpPacket, LpHeader, BOOTSTRAP_SESSION_ID
+├── codec.rs         # Serialization/deserialization
+├── session.rs       # LpSession, cryptographic operations
+├── state_machine.rs # LpStateMachine, state transitions
+├── psk.rs           # PSK derivation utilities
+└── error.rs         # Error types
+```
@@ -0,0 +1,238 @@
+use criterion::{BenchmarkId, Criterion, Throughput, black_box, criterion_group, criterion_main};
+use nym_lp::replay::ReceivingKeyCounterValidator;
+use parking_lot::Mutex;
+use rand::{Rng, SeedableRng};
+use rand_chacha::ChaCha8Rng;
+use std::sync::Arc;
+
+fn bench_sequential_counters(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_sequential");
+    group.sample_size(1000);
+
+    for size in [100, 1000, 10000] {
+        group.throughput(Throughput::Elements(size));
+
+        group.bench_with_input(
+            BenchmarkId::new("sequential_counters", size),
+            &size,
+            |b, &size| {
+                let validator = ReceivingKeyCounterValidator::default();
+                let counters: Vec<u64> = (0..size).collect();
+
+                b.iter(|| {
+                    let mut validator = validator.clone();
+                    for &counter in &counters {
+                        let _ = black_box(validator.will_accept_branchless(counter));
+                        let _ = black_box(validator.mark_did_receive_branchless(counter));
+                    }
+                });
+            },
+        );
+    }
+
+    group.finish();
+}
+
+fn bench_out_of_order_counters(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_out_of_order");
+    group.sample_size(1000);
+
+    for size in [100, 1000, 10000] {
+        group.throughput(Throughput::Elements(size as u64));
+
+        group.bench_with_input(
+            BenchmarkId::new("out_of_order_counters", size),
+            &size,
+            |b, &size| {
+                let validator = ReceivingKeyCounterValidator::default();
+
+                // Create random counters within a valid window
+                let mut rng = ChaCha8Rng::seed_from_u64(42);
+                let counters: Vec<u64> = (0..size).map(|_| rng.gen_range(0..1024)).collect();
+
+                b.iter(|| {
+                    let mut validator = validator.clone();
+                    for &counter in &counters {
+                        let _ = black_box(validator.will_accept_branchless(counter));
+                        let _ = black_box(validator.mark_did_receive_branchless(counter));
+                    }
+                });
+            },
+        );
+    }
+
+    group.finish();
+}
+
+fn bench_thread_safety(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_thread_safety");
+    group.sample_size(1000);
+
+    for size in [100, 1000, 10000] {
+        group.throughput(Throughput::Elements(size));
+
+        group.bench_with_input(
+            BenchmarkId::new("thread_safe_validator", size),
+            &size,
+            |b, &size| {
+                let validator = Arc::new(Mutex::new(ReceivingKeyCounterValidator::default()));
+                let counters: Vec<u64> = (0..size).collect();
+
+                b.iter(|| {
+                    for &counter in &counters {
+                        let result = {
+                            let guard = validator.lock();
+                            black_box(guard.will_accept_branchless(counter))
+                        };
+
+                        if result.is_ok() {
+                            let mut guard = validator.lock();
+                            let _ = black_box(guard.mark_did_receive_branchless(counter));
+                        }
+                    }
+                });
+            },
+        );
+    }
+
+    group.finish();
+}
+
+fn bench_window_sliding(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_window_sliding");
+    group.sample_size(100);
+
+    for window_size in [128, 512, 1024] {
+        group.throughput(Throughput::Elements(window_size));
+
+        group.bench_with_input(
+            BenchmarkId::new("window_sliding", window_size),
+            &window_size,
+            |b, &window_size| {
+                b.iter(|| {
+                    let mut validator = ReceivingKeyCounterValidator::default();
+
+                    // First fill the window with sequential packets
+                    for i in 0..window_size {
+                        let _ = black_box(validator.mark_did_receive_branchless(i));
+                    }
+
+                    // Then jump ahead to force window sliding
+                    let _ = black_box(validator.mark_did_receive_branchless(window_size * 3));
+
+                    // Try some packets in the new window
+                    for i in (window_size * 2 + 1)..(window_size * 3) {
+                        let _ = black_box(validator.will_accept_branchless(i));
+                    }
+                });
+            },
+        );
+    }
+
+    group.finish();
+}
+
+/// Benchmark operations that would benefit from SIMD optimization
+fn bench_core_operations(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_core_operations");
+    group.sample_size(1000);
+
+    // Create validators with different states
+    let empty_validator = ReceivingKeyCounterValidator::default();
+    let mut half_full_validator = ReceivingKeyCounterValidator::default();
+    let mut full_validator = ReceivingKeyCounterValidator::default();
+
+    // Fill validators with different patterns
+    for i in 0..512 {
+        half_full_validator.mark_did_receive_branchless(i).unwrap();
+    }
+
+    for i in 0..1024 {
+        full_validator.mark_did_receive_branchless(i).unwrap();
+    }
+
+    // Benchmark clearing operations
+    group.bench_function("clear_empty_window", |b| {
+        b.iter(|| {
+            let mut validator = empty_validator.clone();
+            // Force window sliding that will clear bitmap
+            let _: () = validator.mark_did_receive_branchless(2000).unwrap();
+            black_box(());
+        })
+    });
+
+    group.bench_function("clear_half_full_window", |b| {
+        b.iter(|| {
+            let mut validator = half_full_validator.clone();
+            // Force window sliding that will clear bitmap
+            let _: () = validator.mark_did_receive_branchless(2000).unwrap();
+            black_box(());
+        })
+    });
+
+    group.bench_function("clear_full_window", |b| {
+        b.iter(|| {
+            let mut validator = full_validator.clone();
+            // Force window sliding that will clear bitmap
+            let _: () = validator.mark_did_receive_branchless(2000).unwrap();
+            black_box(());
+        })
+    });
+
+    group.finish();
+}
+
+/// Benchmark thread safety with different thread counts
+fn bench_concurrency_scaling(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay_concurrency_scaling");
+    group.sample_size(50);
+
+    for thread_count in [1, 2, 4, 8] {
+        group.bench_with_input(
+            BenchmarkId::new("mutex_threads", thread_count),
+            &thread_count,
+            |b, &thread_count| {
+                b.iter(|| {
+                    let validator = Arc::new(Mutex::new(ReceivingKeyCounterValidator::default()));
+                    let mut handles = Vec::new();
+
+                    for t in 0..thread_count {
+                        let validator_clone = Arc::clone(&validator);
+                        let handle = std::thread::spawn(move || {
+                            let mut success_count = 0;
+                            for i in 0..100 {
+                                let counter = t * 1000 + i;
+                                let mut guard = validator_clone.lock();
+                                if guard.mark_did_receive_branchless(counter as u64).is_ok() {
+                                    success_count += 1;
+                                }
+                            }
+                            success_count
+                        });
+                        handles.push(handle);
+                    }
+
+                    let mut total = 0;
+                    for handle in handles {
+                        total += handle.join().unwrap();
+                    }
+
+                    black_box(total)
+                })
+            },
+        );
+    }
+
+    group.finish();
+}
+
+criterion_group!(
+    replay_benches,
+    bench_sequential_counters,
+    bench_out_of_order_counters,
+    bench_thread_safety,
+    bench_window_sliding,
+    bench_core_operations,
+    bench_concurrency_scaling
+);
+criterion_main!(replay_benches);
@@ -0,0 +1,85 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{noise_protocol::NoiseError, replay::ReplayError};
+use nym_crypto::asymmetric::ed25519::Ed25519RecoveryError;
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum LpError {
+    #[error("IO Error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    #[error("Snow Error: {0}")]
+    SnowKeyError(#[from] snow::Error),
+
+    #[error("Snow Pattern Error: {0}")]
+    SnowPatternError(String),
+
+    #[error("Noise Protocol Error: {0}")]
+    NoiseError(#[from] NoiseError),
+
+    #[error("Replay detected: {0}")]
+    Replay(#[from] ReplayError),
+
+    #[error("Invalid packet format: {0}")]
+    InvalidPacketFormat(String),
+
+    #[error("Invalid message type: {0}")]
+    InvalidMessageType(u16),
+
+    #[error("Payload too large: {0}")]
+    PayloadTooLarge(usize),
+
+    #[error("Insufficient buffer size provided")]
+    InsufficientBufferSize,
+
+    #[error("Attempted operation on closed session")]
+    SessionClosed,
+
+    #[error("Internal error: {0}")]
+    Internal(String),
+
+    #[error("Invalid state transition: tried input {input:?} in state {state:?}")]
+    InvalidStateTransition { state: String, input: String },
+
+    #[error("Invalid payload size: expected {expected}, got {actual}")]
+    InvalidPayloadSize { expected: usize, actual: usize },
+
+    #[error("Deserialization error: {0}")]
+    DeserializationError(String),
+
+    #[error("KKT protocol error: {0}")]
+    KKTError(String),
+
+    #[error(transparent)]
+    InvalidBase58String(#[from] bs58::decode::Error),
+
+    /// Session ID from incoming packet does not match any known session.
+    #[error("Received packet with unknown session ID: {0}")]
+    UnknownSessionId(u32),
+
+    /// Invalid state transition attempt in the state machine.
+    #[error("Invalid input '{input}' for current state '{state}'")]
+    InvalidStateTransitionAttempt { state: String, input: String },
+
+    /// Session is closed.
+    #[error("Session is closed")]
+    LpSessionClosed,
+
+    /// Session is processing an input event.
+    #[error("Session is processing an input event")]
+    LpSessionProcessing,
+
+    /// State machine not found.
+    #[error("State machine not found for lp_id: {lp_id}")]
+    StateMachineNotFound { lp_id: u32 },
+
+    /// Ed25519 to X25519 conversion error.
+    #[error("Ed25519 key conversion error: {0}")]
+    Ed25519RecoveryError(#[from] Ed25519RecoveryError),
+
+    /// Outer AEAD authentication tag verification failed.
+    #[error("AEAD authentication tag verification failed")]
+    AeadTagMismatch,
+}
@@ -0,0 +1,200 @@
+use std::fmt::{self, Display, Formatter};
+use std::ops::Deref;
+use std::str::FromStr;
+
+use nym_sphinx::{PrivateKey as SphinxPrivateKey, PublicKey as SphinxPublicKey};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use crate::LpError;
+
+#[derive(Clone)]
+pub struct PrivateKey(SphinxPrivateKey);
+
+impl fmt::Debug for PrivateKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("PrivateKey").field(&"[REDACTED]").finish()
+    }
+}
+
+impl Deref for PrivateKey {
+    type Target = SphinxPrivateKey;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl Default for PrivateKey {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl PrivateKey {
+    pub fn new() -> Self {
+        let private_key = SphinxPrivateKey::random();
+        Self(private_key)
+    }
+
+    pub fn to_base58_string(&self) -> String {
+        bs58::encode(self.0.to_bytes()).into_string()
+    }
+
+    pub fn from_base58_string(s: &str) -> Result<Self, LpError> {
+        let bytes: [u8; 32] = bs58::decode(s).into_vec()?.try_into().unwrap();
+        Ok(PrivateKey(SphinxPrivateKey::from(bytes)))
+    }
+
+    pub fn from_bytes(bytes: &[u8; 32]) -> Self {
+        PrivateKey(SphinxPrivateKey::from(*bytes))
+    }
+
+    pub fn public_key(&self) -> PublicKey {
+        let public_key = SphinxPublicKey::from(&self.0);
+        PublicKey(public_key)
+    }
+}
+
+#[derive(Clone)]
+pub struct PublicKey(SphinxPublicKey);
+
+impl fmt::Debug for PublicKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("PublicKey")
+            .field(&self.to_base58_string())
+            .finish()
+    }
+}
+
+impl Deref for PublicKey {
+    type Target = SphinxPublicKey;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl PublicKey {
+    pub fn to_base58_string(&self) -> String {
+        bs58::encode(self.0.as_bytes()).into_string()
+    }
+
+    pub fn from_base58_string(s: &str) -> Result<Self, LpError> {
+        let bytes: [u8; 32] = bs58::decode(s).into_vec()?.try_into().unwrap();
+        Ok(PublicKey(SphinxPublicKey::from(bytes)))
+    }
+
+    pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self, LpError> {
+        Ok(PublicKey(SphinxPublicKey::from(*bytes)))
+    }
+
+    pub fn as_bytes(&self) -> &[u8; 32] {
+        self.0.as_bytes()
+    }
+}
+
+impl Default for PublicKey {
+    fn default() -> Self {
+        let private_key = PrivateKey::default();
+        private_key.public_key()
+    }
+}
+
+pub struct Keypair {
+    private_key: PrivateKey,
+    public_key: PublicKey,
+}
+
+impl Default for Keypair {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Keypair {
+    pub fn new() -> Self {
+        let private_key = PrivateKey::default();
+        let public_key = private_key.public_key();
+        Self {
+            private_key,
+            public_key,
+        }
+    }
+
+    pub fn from_private_key(private_key: PrivateKey) -> Self {
+        let public_key = private_key.public_key();
+        Self {
+            private_key,
+            public_key,
+        }
+    }
+
+    pub fn from_keys(private_key: PrivateKey, public_key: PublicKey) -> Self {
+        Self {
+            private_key,
+            public_key,
+        }
+    }
+
+    pub fn private_key(&self) -> &PrivateKey {
+        &self.private_key
+    }
+
+    pub fn public_key(&self) -> &PublicKey {
+        &self.public_key
+    }
+}
+
+impl From<KeypairReadable> for Keypair {
+    fn from(keypair: KeypairReadable) -> Self {
+        Self {
+            private_key: PrivateKey::from_base58_string(&keypair.private).unwrap(),
+            public_key: PublicKey::from_base58_string(&keypair.public).unwrap(),
+        }
+    }
+}
+
+impl From<&Keypair> for KeypairReadable {
+    fn from(keypair: &Keypair) -> Self {
+        Self {
+            private: keypair.private_key.to_base58_string(),
+            public: keypair.public_key.to_base58_string(),
+        }
+    }
+}
+impl FromStr for PrivateKey {
+    type Err = LpError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        PrivateKey::from_base58_string(s)
+    }
+}
+
+impl Display for PrivateKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.to_base58_string())
+    }
+}
+
+impl Display for PublicKey {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.to_base58_string())
+    }
+}
+
+#[derive(Serialize, serde::Deserialize, Clone, ToSchema, Debug)]
+pub struct KeypairReadable {
+    private: String,
+    public: String,
+}
+
+impl KeypairReadable {
+    pub fn private_key(&self) -> Result<PrivateKey, LpError> {
+        PrivateKey::from_base58_string(&self.private)
+    }
+
+    pub fn public_key(&self) -> Result<PublicKey, LpError> {
+        PublicKey::from_base58_string(&self.public)
+    }
+}
@@ -0,0 +1,500 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! KKT (Key Encapsulation Transport) orchestration for nym-lp sessions.
+//!
+//! This module provides functions to perform KKT key exchange before establishing
+//! an nym-lp session. The KKT protocol allows secure distribution of post-quantum
+//! KEM public keys, which are then used with PSQ to derive a strong pre-shared key
+//! for the Noise protocol.
+//!
+//! # Protocol Flow
+//!
+//! 1. **Client (Initiator)**:
+//!    - Calls `create_request()` to generate a KKT request
+//!    - Sends `LpMessage::KKTRequest` to gateway
+//!    - Receives `LpMessage::KKTResponse` from gateway
+//!    - Calls `process_response()` to validate and extract gateway's KEM key
+//!
+//! 2. **Gateway (Responder)**:
+//!    - Receives `LpMessage::KKTRequest` from client
+//!    - Calls `handle_request()` to validate request and generate response
+//!    - Sends `LpMessage::KKTResponse` to client
+//!
+//! # Example
+//!
+//! ```ignore
+//! use nym_lp::kkt_orchestrator::{create_request, process_response, handle_request};
+//! use nym_lp::message::{KKTRequestData, KKTResponseData};
+//! use nym-kkt::ciphersuite::{Ciphersuite, KEM, HashFunction, SignatureScheme, EncapsulationKey};
+//!
+//! // Setup ciphersuite
+//! let ciphersuite = Ciphersuite::resolve_ciphersuite(
+//!     KEM::X25519,
+//!     HashFunction::Blake3,
+//!     SignatureScheme::Ed25519,
+//!     None,
+//! ).unwrap();
+//!
+//! // Client: Create request
+//! let (session_secret, client_context, request_data) = create_request(
+//!     ciphersuite,
+//!     &client_signing_key,
+//!     &responder_dh_public_key
+//! ).unwrap();
+//!
+//! // Gateway: Handle request
+//! let response_data = handle_request(
+//!     &request_data,
+//!     Some(&client_verification_key),
+//!     &gateway_signing_key,
+//!     &gateway_dh_private_key,
+//!     &gateway_kem_public_key,
+//! ).unwrap();
+//!
+//! // Client: Process response
+//! let gateway_kem_key = process_response(
+//!     client_context,
+//!     &session_secret,
+//!     &gateway_verification_key,
+//!     &expected_key_hash,
+//!     &response_data,
+//! ).unwrap();
+//! ```
+
+use crate::LpError;
+use crate::message::{KKTRequestData, KKTResponseData};
+use nym_crypto::asymmetric::ed25519;
+use nym_kkt::ciphersuite::{Ciphersuite, EncapsulationKey};
+use nym_kkt::context::KKTContext;
+use nym_kkt::encryption::KKTSessionSecret;
+use nym_kkt::kkt::{handle_kem_request, request_kem_key, validate_kem_response};
+
+/// Creates a KKT request to obtain the responder's KEM public key.
+///
+/// This is called by the **client (initiator)** to begin the KKT exchange.
+/// The returned context must be used when processing the response.
+///
+/// # Arguments
+/// * `ciphersuite` - Negotiated ciphersuite (KEM, hash, signature algorithms)
+/// * `signing_key` - Client's Ed25519 signing key for authentication
+/// * `responder_dh_public_key` - Gateway's x25519 public key (from directory)
+///
+/// # Returns
+/// * `KKTSessionSecret` - Session secret key to encrypt/decrypt KKT messages for this session
+/// * `KKTContext` - Context to use when validating the response
+/// * `KKTRequestData` - Serialized KKT request frame to send to gateway
+///
+/// # Errors
+/// Returns `LpError::KKTError` if KKT request generation fails.
+pub fn create_request(
+    ciphersuite: Ciphersuite,
+    signing_key: &ed25519::PrivateKey,
+    responder_dh_public_key: &nym_sphinx::PublicKey,
+) -> Result<(KKTSessionSecret, KKTContext, KKTRequestData), LpError> {
+    // Note: Uses rand 0.9's thread_rng() to match nym-kkt's rand version
+    let mut rng = rand09::rng();
+    let (session_secret, context, request_bytes) =
+        request_kem_key(&mut rng, ciphersuite, signing_key, &responder_dh_public_key)
+            .map_err(|e| LpError::KKTError(e.to_string()))?;
+
+    Ok((session_secret, context, KKTRequestData(request_bytes)))
+}
+
+/// Processes a KKT response and extracts the responder's KEM public key.
+///
+/// This is called by the **client (initiator)** after receiving a KKT response
+/// from the gateway. It verifies the signature and validates the key hash.
+///
+/// # Arguments
+/// * `context` - Context from the initial `create_request()` call
+/// * `session_secret` - The KKT session secret key from the initial `create_request()` call
+/// * `responder_vk` - Responder's Ed25519 verification key (from directory)
+/// * `expected_key_hash` - Expected hash of responder's KEM key (from directory)
+/// * `response_data` - Serialized KKT response frame from responder
+///
+/// # Returns
+/// * `EncapsulationKey` - Authenticated KEM public key of the responder
+///
+/// # Errors
+/// Returns `LpError::KKTError` if:
+/// - Response deserialization fails
+/// - Signature verification fails
+/// - Key hash doesn't match expected value
+pub fn process_response<'a>(
+    mut context: KKTContext,
+    session_secret: &KKTSessionSecret,
+    responder_vk: &ed25519::PublicKey,
+    expected_key_hash: &[u8],
+    response_data: &KKTResponseData,
+) -> Result<EncapsulationKey<'a>, LpError> {
+    validate_kem_response(
+        &mut context,
+        session_secret,
+        responder_vk,
+        expected_key_hash,
+        &response_data.0,
+    )
+    .map_err(|e| LpError::KKTError(e.to_string()))
+}
+
+/// Handles a KKT request and generates a signed response with the responder's KEM key.
+///
+/// This is called by the **gateway (responder)** when receiving a KKT request
+/// from a client. It validates the request signature (if authenticated) and
+/// responds with the gateway's KEM public key, signed for authenticity.
+///
+/// # Arguments
+/// * `request_data` - Serialized KKT request frame from initiator
+/// * `initiator_vk` - Initiator's Ed25519 verification key (None for anonymous)
+/// * `responder_signing_key` - Gateway's Ed25519 signing key
+/// * `responder_dh_private_key` - Gateway's x25519 private key
+/// * `responder_kem_key` - Gateway's KEM public key to send
+///
+/// # Returns
+/// * `KKTResponseData` - Signed response frame containing the KEM public key
+///
+/// # Errors
+/// Returns `LpError::KKTError` if:
+/// - Request deserialization fails
+/// - Signature verification fails (if authenticated)
+/// - Response generation fails
+pub fn handle_request<'a>(
+    request_data: &KKTRequestData,
+    initiator_vk: Option<&ed25519::PublicKey>,
+    responder_signing_key: &ed25519::PrivateKey,
+    responder_dh_private_key: &nym_sphinx::PrivateKey,
+    responder_kem_key: &EncapsulationKey<'a>,
+) -> Result<KKTResponseData, LpError> {
+    let mut rng = rand09::rng();
+    // Handle the request and generate response
+    let response_bytes = handle_kem_request(
+        &mut rng,
+        &request_data.0,
+        initiator_vk,
+        responder_signing_key,
+        responder_dh_private_key,
+        responder_kem_key,
+    )
+    .map_err(|e| LpError::KKTError(e.to_string()))?;
+
+    Ok(KKTResponseData(response_bytes))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nym_kkt::ciphersuite::{HashFunction, KEM, SignatureScheme};
+    use nym_kkt::key_utils::{
+        generate_keypair_ed25519, generate_keypair_libcrux, generate_keypair_x25519,
+        hash_encapsulation_key,
+    };
+    use nym_kkt::kkt::initiator_ingest_response;
+    use rand09::RngCore;
+
+    #[test]
+    fn test_kkt_roundtrip_authenticated() {
+        let mut rng = rand09::rng();
+
+        // Generate Ed25519 keypairs for both parties
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        let (responder_x25519_sk, responder_x25519_pk) = generate_keypair_x25519();
+
+        // Generate responder's KEM keypair (X25519 for testing)
+        let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+        // Create ciphersuite
+        let ciphersuite = Ciphersuite::resolve_ciphersuite(
+            KEM::X25519,
+            HashFunction::Blake3,
+            SignatureScheme::Ed25519,
+            None,
+        )
+        .unwrap();
+
+        // Hash the KEM key (simulating directory storage)
+        let key_hash = hash_encapsulation_key(
+            &ciphersuite.hash_function(),
+            ciphersuite.hash_len(),
+            &responder_kem_key.encode(),
+        );
+
+        // Client: Create request
+        let (session_secret, context, request_data) = create_request(
+            ciphersuite,
+            initiator_ed25519_keypair.private_key(),
+            &responder_x25519_pk,
+        )
+        .unwrap();
+
+        // Gateway: Handle request
+        let response_data = handle_request(
+            &request_data,
+            Some(initiator_ed25519_keypair.public_key()),
+            responder_ed25519_keypair.private_key(),
+            &responder_x25519_sk,
+            &responder_kem_key,
+        )
+        .unwrap();
+
+        // Client: Process response
+        let obtained_key = process_response(
+            context,
+            &session_secret,
+            responder_ed25519_keypair.public_key(),
+            &key_hash,
+            &response_data,
+        )
+        .unwrap();
+
+        // Verify we got the correct KEM key
+        assert_eq!(obtained_key.encode(), responder_kem_key.encode());
+    }
+
+    // #[test]
+    // fn test_kkt_roundtrip_anonymous() {
+    //     let mut rng = rand09::rng();
+
+    //     // Only responder has keys (anonymous initiator)
+    //     // Generate Ed25519 keypairs for both parties
+
+    //     let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+    //     let (responder_x25519_sk, responder_x25519_pk) = generate_keypair_x25519();
+
+    //     let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+    //     let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+    //     let ciphersuite = Ciphersuite::resolve_ciphersuite(
+    //         KEM::X25519,
+    //         HashFunction::Blake3,
+    //         SignatureScheme::Ed25519,
+    //         None,
+    //     )
+    //     .unwrap();
+
+    //     let key_hash = hash_encapsulation_key(
+    //         &ciphersuite.hash_function(),
+    //         ciphersuite.hash_len(),
+    //         &responder_kem_key.encode(),
+    //     );
+
+    //     // Anonymous initiator - use anonymous_initiator_process directly
+    //     use nym_kkt::kkt::anonymous_initiator_process;
+    //     let (mut context, request_frame) =
+    //         anonymous_initiator_process(&mut rng, ciphersuite).unwrap();
+    //     let request_data = KKTRequestData(request_frame.to_bytes());
+
+    //     // Gateway: Handle anonymous request
+    //     let response_data = handle_request(
+    //         &request_data,
+    //         None,
+    //         responder_ed25519_keypair.private_key(),
+    //         &responder_x25519_sk,
+    //         &responder_kem_key,
+    //     )
+    //     .unwrap();
+
+    //     // Initiator: Validate response
+    //     let obtained_key = initiator_ingest_response(
+    //         &mut context,
+    //         responder_ed25519_keypair.public_key(),
+    //         &key_hash,
+    //         &response_data.0,
+    //     )
+    //     .unwrap();
+
+    //     assert_eq!(obtained_key.encode(), responder_kem_key.encode());
+    // }
+
+    #[test]
+    fn test_invalid_signature_rejected() {
+        let mut rng = rand09::rng();
+
+        // Generate Ed25519 keypairs for both parties
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        let (responder_x25519_sk, responder_x25519_pk) = generate_keypair_x25519();
+
+        // Different keypair for wrong signature
+        let mut wrong_secret = [0u8; 32];
+        rng.fill_bytes(&mut wrong_secret);
+        let wrong_keypair = ed25519::KeyPair::from_secret(wrong_secret, 2);
+
+        let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+        let ciphersuite = Ciphersuite::resolve_ciphersuite(
+            KEM::X25519,
+            HashFunction::Blake3,
+            SignatureScheme::Ed25519,
+            None,
+        )
+        .unwrap();
+
+        let (_session_secret, _context, request_data) = create_request(
+            ciphersuite,
+            initiator_ed25519_keypair.private_key(),
+            &responder_x25519_pk,
+        )
+        .unwrap();
+
+        // Gateway handles request but we provide WRONG verification key
+        let result = handle_request(
+            &request_data,
+            Some(wrong_keypair.public_key()), // Wrong key!
+            responder_ed25519_keypair.private_key(),
+            &responder_x25519_sk,
+            &responder_kem_key,
+        );
+
+        // Should fail signature verification
+        assert!(result.is_err());
+        if let Err(LpError::KKTError(_)) = result {
+            // Expected
+        } else {
+            panic!("Expected KKTError");
+        }
+    }
+
+    #[test]
+    fn test_hash_mismatch_rejected() {
+        let mut rng = rand09::rng();
+
+        // Generate Ed25519 keypairs for both parties
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        let (responder_x25519_sk, responder_x25519_pk) = generate_keypair_x25519();
+
+        let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+        let ciphersuite = Ciphersuite::resolve_ciphersuite(
+            KEM::X25519,
+            HashFunction::Blake3,
+            SignatureScheme::Ed25519,
+            None,
+        )
+        .unwrap();
+
+        // Use WRONG hash
+        let wrong_hash = [0u8; 32];
+
+        let (session_secret, context, request_data) = create_request(
+            ciphersuite,
+            initiator_ed25519_keypair.private_key(),
+            &responder_x25519_pk,
+        )
+        .unwrap();
+
+        let response_data = handle_request(
+            &request_data,
+            Some(initiator_ed25519_keypair.public_key()),
+            responder_ed25519_keypair.private_key(),
+            &responder_x25519_sk,
+            &responder_kem_key,
+        )
+        .unwrap();
+
+        // Client validates with WRONG hash
+        let result = process_response(
+            context,
+            &session_secret,
+            responder_ed25519_keypair.public_key(),
+            &wrong_hash, // Wrong!
+            &response_data,
+        );
+
+        // Should fail hash validation
+        assert!(result.is_err());
+        if let Err(LpError::KKTError(_)) = result {
+            // Expected
+        } else {
+            panic!("Expected KKTError");
+        }
+    }
+
+    #[test]
+    fn test_malformed_request_rejected() {
+        let mut rng = rand09::rng();
+
+        let mut responder_secret = [0u8; 32];
+        rng.fill_bytes(&mut responder_secret);
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        let (responder_x25519_sk, _responder_x25519_pk) = generate_keypair_x25519();
+
+        let (_, responder_kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let responder_kem_key = EncapsulationKey::X25519(responder_kem_pk);
+
+        // Create malformed request data (invalid bytes)
+        let malformed_request = KKTRequestData(vec![0xFF; 100]);
+
+        let result = handle_request(
+            &malformed_request,
+            None,
+            responder_ed25519_keypair.private_key(),
+            &responder_x25519_sk,
+            &responder_kem_key,
+        );
+
+        // Should fail to parse
+        assert!(result.is_err());
+        if let Err(LpError::KKTError(_)) = result {
+            // Expected
+        } else {
+            panic!("Expected KKTError");
+        }
+    }
+
+    #[test]
+    fn test_malformed_response_rejected() {
+        let mut rng = rand09::rng();
+
+        // Generate Ed25519 keypairs for both parties
+        let initiator_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(0));
+        let responder_ed25519_keypair = generate_keypair_ed25519(&mut rng, Some(1));
+
+        let (_responder_x25519_sk, responder_x25519_pk) = generate_keypair_x25519();
+
+        let ciphersuite = Ciphersuite::resolve_ciphersuite(
+            KEM::X25519,
+            HashFunction::Blake3,
+            SignatureScheme::Ed25519,
+            None,
+        )
+        .unwrap();
+
+        let (session_secret, context, _request_data) = create_request(
+            ciphersuite,
+            initiator_ed25519_keypair.private_key(),
+            &responder_x25519_pk,
+        )
+        .unwrap();
+
+        // Create malformed response data
+        let malformed_response = KKTResponseData(vec![0xFF; 100]);
+        let key_hash = [0u8; 32];
+
+        let result = process_response(
+            context,
+            &session_secret,
+            responder_ed25519_keypair.public_key(),
+            &key_hash,
+            &malformed_response,
+        );
+
+        // Should fail to parse
+        assert!(result.is_err());
+        if let Err(LpError::KKTError(_)) = result {
+            // Expected
+        } else {
+            panic!("Expected KKTError");
+        }
+    }
+}
@@ -0,0 +1,329 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod codec;
+pub mod error;
+pub mod keypair;
+pub mod kkt_orchestrator;
+pub mod message;
+pub mod noise_protocol;
+pub mod packet;
+pub mod psk;
+pub mod replay;
+pub mod session;
+mod session_integration;
+pub mod session_manager;
+
+pub use error::LpError;
+pub use message::{ClientHelloData, LpMessage};
+pub use packet::{BOOTSTRAP_RECEIVER_IDX, LpPacket, OuterHeader};
+pub use replay::{ReceivingKeyCounterValidator, ReplayError};
+pub use session::{LpSession, generate_fresh_salt};
+pub use session_manager::SessionManager;
+
+// Add the new state machine module
+pub mod state_machine;
+pub use state_machine::LpStateMachine;
+
+pub const NOISE_PATTERN: &str = "Noise_XKpsk3_25519_ChaChaPoly_SHA256";
+pub const NOISE_PSK_INDEX: u8 = 3;
+
+#[cfg(test)]
+pub fn sessions_for_tests() -> (LpSession, LpSession) {
+    use crate::keypair::Keypair;
+    use nym_crypto::asymmetric::ed25519;
+
+    // X25519 keypairs for Noise protocol
+    let keypair_1 = Keypair::default();
+    let keypair_2 = Keypair::default();
+
+    // Use a fixed receiver_index for deterministic tests
+    let receiver_index: u32 = 12345;
+
+    // Ed25519 keypairs for PSQ authentication (placeholders for testing)
+    let ed25519_keypair_1 = ed25519::KeyPair::from_secret([1u8; 32], 0);
+    let ed25519_keypair_2 = ed25519::KeyPair::from_secret([2u8; 32], 1);
+
+    // Use consistent salt for deterministic tests
+    let salt = [1u8; 32];
+
+    // PSQ will always derive the PSK during handshake using X25519 as DHKEM
+
+    let initiator_session = LpSession::new(
+        receiver_index,
+        true,
+        (
+            ed25519_keypair_1.private_key(),
+            ed25519_keypair_1.public_key(),
+        ),
+        keypair_1.private_key(),
+        ed25519_keypair_2.public_key(),
+        keypair_2.public_key(),
+        &salt,
+    )
+    .expect("Test session creation failed");
+
+    let responder_session = LpSession::new(
+        receiver_index,
+        false,
+        (
+            ed25519_keypair_2.private_key(),
+            ed25519_keypair_2.public_key(),
+        ),
+        keypair_2.private_key(),
+        ed25519_keypair_1.public_key(),
+        keypair_1.public_key(),
+        &salt,
+    )
+    .expect("Test session creation failed");
+
+    (initiator_session, responder_session)
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::message::LpMessage;
+    use crate::packet::{LpHeader, LpPacket, TRAILER_LEN};
+    use crate::session_manager::SessionManager;
+    use crate::{LpError, sessions_for_tests};
+    use bytes::BytesMut;
+
+    // Import the new standalone functions
+    use crate::codec::{parse_lp_packet, serialize_lp_packet};
+
+    #[test]
+    fn test_replay_protection_integration() {
+        // Create session
+        let session = sessions_for_tests().0;
+
+        // === Packet 1 (Counter 0 - Should succeed) ===
+        let packet1 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: 42, // Matches session's sending_index assumption for this test
+                counter: 0,
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize packet
+        let mut buf1 = BytesMut::new();
+        serialize_lp_packet(&packet1, &mut buf1, None).unwrap();
+
+        // Parse packet
+        let parsed_packet1 = parse_lp_packet(&buf1, None).unwrap();
+
+        // Perform replay check (should pass)
+        session
+            .receiving_counter_quick_check(parsed_packet1.header.counter)
+            .expect("Initial packet failed replay check");
+
+        // Mark received (simulating successful processing)
+        session
+            .receiving_counter_mark(parsed_packet1.header.counter)
+            .expect("Failed to mark initial packet received");
+
+        // === Packet 2 (Counter 0 - Replay, should fail check) ===
+        let packet2 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: 42,
+                counter: 0, // Same counter as before (replay)
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize packet
+        let mut buf2 = BytesMut::new();
+        serialize_lp_packet(&packet2, &mut buf2, None).unwrap();
+
+        // Parse packet
+        let parsed_packet2 = parse_lp_packet(&buf2, None).unwrap();
+
+        // Perform replay check (should fail)
+        let replay_result = session.receiving_counter_quick_check(parsed_packet2.header.counter);
+        assert!(replay_result.is_err());
+        match replay_result.unwrap_err() {
+            LpError::Replay(e) => {
+                assert!(matches!(e, crate::replay::ReplayError::DuplicateCounter));
+            }
+            e => panic!("Expected replay error, got {:?}", e),
+        }
+        // Do not mark received as it failed validation
+
+        // === Packet 3 (Counter 1 - Should succeed) ===
+        let packet3 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: 42,
+                counter: 1, // Incremented counter
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize packet
+        let mut buf3 = BytesMut::new();
+        serialize_lp_packet(&packet3, &mut buf3, None).unwrap();
+
+        // Parse packet
+        let parsed_packet3 = parse_lp_packet(&buf3, None).unwrap();
+
+        // Perform replay check (should pass)
+        session
+            .receiving_counter_quick_check(parsed_packet3.header.counter)
+            .expect("Packet 3 failed replay check");
+
+        // Mark received
+        session
+            .receiving_counter_mark(parsed_packet3.header.counter)
+            .expect("Failed to mark packet 3 received");
+
+        // Verify validator state directly on the session
+        let state = session.current_packet_cnt();
+        assert_eq!(state.0, 2); // Next expected counter (correct - was 1, now expects 2)
+        assert_eq!(state.1, 2); // Total marked received (correct - packets 1 and 3)
+    }
+
+    #[test]
+    fn test_session_manager_integration() {
+        use nym_crypto::asymmetric::ed25519;
+
+        // Create session manager
+        let local_manager = SessionManager::new();
+        let remote_manager = SessionManager::new();
+
+        // Generate Ed25519 keypairs for PSQ authentication
+        let ed25519_keypair_local = ed25519::KeyPair::from_secret([8u8; 32], 0);
+        let ed25519_keypair_remote = ed25519::KeyPair::from_secret([9u8; 32], 1);
+
+        // Use fixed receiver_index for deterministic test
+        let receiver_index: u32 = 54321;
+
+        // Test salt
+        let salt = [46u8; 32];
+
+        // Create a session via manager
+        let _ = local_manager
+            .create_session_state_machine(
+                receiver_index,
+                (
+                    ed25519_keypair_local.private_key(),
+                    ed25519_keypair_local.public_key(),
+                ),
+                ed25519_keypair_remote.public_key(),
+                true,
+                &salt,
+            )
+            .unwrap();
+
+        let _ = remote_manager
+            .create_session_state_machine(
+                receiver_index,
+                (
+                    ed25519_keypair_remote.private_key(),
+                    ed25519_keypair_remote.public_key(),
+                ),
+                ed25519_keypair_local.public_key(),
+                false,
+                &salt,
+            )
+            .unwrap();
+        // === Packet 1 (Counter 0 - Should succeed) ===
+        let packet1 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: receiver_index,
+                counter: 0,
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize
+        let mut buf1 = BytesMut::new();
+        serialize_lp_packet(&packet1, &mut buf1, None).unwrap();
+
+        // Parse
+        let parsed_packet1 = parse_lp_packet(&buf1, None).unwrap();
+
+        // Process via SessionManager method (which should handle checks + marking)
+        // NOTE: We might need a method on SessionManager/LpSession like `process_incoming_packet`
+        //       that encapsulates parse -> check -> process_noise -> mark.
+        //       For now, we simulate the steps using the retrieved session.
+
+        // Perform replay check
+        local_manager
+            .receiving_counter_quick_check(receiver_index, parsed_packet1.header.counter)
+            .expect("Packet 1 check failed");
+        // Mark received
+        local_manager
+            .receiving_counter_mark(receiver_index, parsed_packet1.header.counter)
+            .expect("Packet 1 mark failed");
+
+        // === Packet 2 (Counter 1 - Should succeed on same session) ===
+        let packet2 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: receiver_index,
+                counter: 1,
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize
+        let mut buf2 = BytesMut::new();
+        serialize_lp_packet(&packet2, &mut buf2, None).unwrap();
+
+        // Parse
+        let parsed_packet2 = parse_lp_packet(&buf2, None).unwrap();
+
+        // Perform replay check
+        local_manager
+            .receiving_counter_quick_check(receiver_index, parsed_packet2.header.counter)
+            .expect("Packet 2 check failed");
+        // Mark received
+        local_manager
+            .receiving_counter_mark(receiver_index, parsed_packet2.header.counter)
+            .expect("Packet 2 mark failed");
+
+        // === Packet 3 (Counter 0 - Replay, should fail check) ===
+        let packet3 = LpPacket {
+            header: LpHeader {
+                protocol_version: 1,
+                reserved: 0,
+                receiver_idx: receiver_index,
+                counter: 0, // Replay of first packet
+            },
+            message: LpMessage::Busy,
+            trailer: [0u8; TRAILER_LEN],
+        };
+
+        // Serialize
+        let mut buf3 = BytesMut::new();
+        serialize_lp_packet(&packet3, &mut buf3, None).unwrap();
+
+        // Parse
+        let parsed_packet3 = parse_lp_packet(&buf3, None).unwrap();
+
+        // Perform replay check (should fail)
+        let replay_result = local_manager
+            .receiving_counter_quick_check(receiver_index, parsed_packet3.header.counter);
+        assert!(replay_result.is_err());
+        match replay_result.unwrap_err() {
+            LpError::Replay(e) => {
+                assert!(matches!(e, crate::replay::ReplayError::DuplicateCounter));
+            }
+            e => panic!("Expected replay error for packet 3, got {:?}", e),
+        }
+        // Do not mark received
+    }
+}
@@ -0,0 +1,415 @@
+use std::fmt::{self, Display};
+
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+use bytes::{BufMut, BytesMut};
+use num_enum::{IntoPrimitive, TryFromPrimitive};
+use serde::{Deserialize, Serialize};
+
+/// Data structure for the ClientHello message
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ClientHelloData {
+    /// Client-proposed receiver index for session identification (4 bytes)
+    /// Auto-generated randomly by the client
+    pub receiver_index: u32,
+    /// Client's LP x25519 public key (32 bytes) - derived from Ed25519 key
+    pub client_lp_public_key: [u8; 32],
+    /// Client's Ed25519 public key (32 bytes) - for PSQ authentication
+    pub client_ed25519_public_key: [u8; 32],
+    /// Salt for PSK derivation (32 bytes: 8-byte timestamp + 24-byte nonce)
+    pub salt: [u8; 32],
+}
+
+impl ClientHelloData {
+    /// Generates a new ClientHelloData with fresh salt.
+    ///
+    /// Salt format: 8 bytes timestamp (u64 LE) + 24 bytes random nonce
+    ///
+    /// # Arguments
+    /// * `client_lp_public_key` - Client's x25519 public key (derived from Ed25519)
+    /// * `client_ed25519_public_key` - Client's Ed25519 public key (for PSQ authentication)
+    pub fn new_with_fresh_salt(
+        client_lp_public_key: [u8; 32],
+        client_ed25519_public_key: [u8; 32],
+    ) -> Self {
+        use std::time::{SystemTime, UNIX_EPOCH};
+
+        // Generate salt: timestamp + nonce
+        let mut salt = [0u8; 32];
+
+        // First 8 bytes: current timestamp as u64 little-endian
+        let timestamp = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("System time before UNIX epoch")
+            .as_secs();
+        salt[..8].copy_from_slice(&timestamp.to_le_bytes());
+
+        // Last 24 bytes: random nonce
+        use rand::RngCore;
+        rand::thread_rng().fill_bytes(&mut salt[8..]);
+
+        Self {
+            receiver_index: rand::random(), // Auto-generate random receiver index
+            client_lp_public_key,
+            client_ed25519_public_key,
+            salt,
+        }
+    }
+
+    /// Extracts the timestamp from the salt.
+    ///
+    /// # Returns
+    /// Unix timestamp in seconds
+    pub fn extract_timestamp(&self) -> u64 {
+        let mut timestamp_bytes = [0u8; 8];
+        timestamp_bytes.copy_from_slice(&self.salt[..8]);
+        u64::from_le_bytes(timestamp_bytes)
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, IntoPrimitive, TryFromPrimitive)]
+#[repr(u16)]
+pub enum MessageType {
+    Busy = 0x0000,
+    Handshake = 0x0001,
+    EncryptedData = 0x0002,
+    ClientHello = 0x0003,
+    KKTRequest = 0x0004,
+    KKTResponse = 0x0005,
+    ForwardPacket = 0x0006,
+    /// Receiver index collision - client should retry with new index
+    Collision = 0x0007,
+    /// Acknowledgment - gateway confirms receipt of message
+    Ack = 0x0008,
+    /// Subsession request - client initiates subsession creation
+    SubsessionRequest = 0x0009,
+    /// Subsession KK1 - first message of Noise KK handshake
+    SubsessionKK1 = 0x000A,
+    /// Subsession KK2 - second message of Noise KK handshake
+    SubsessionKK2 = 0x000B,
+    /// Subsession ready - subsession established confirmation
+    SubsessionReady = 0x000C,
+    /// Subsession abort - race winner tells loser to become responder
+    SubsessionAbort = 0x000D,
+}
+
+impl MessageType {
+    pub(crate) fn from_u16(value: u16) -> Option<Self> {
+        MessageType::try_from(value).ok()
+    }
+
+    pub fn to_u16(&self) -> u16 {
+        u16::from(*self)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HandshakeData(pub Vec<u8>);
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EncryptedDataPayload(pub Vec<u8>);
+
+/// KKT request frame data (serialized KKTFrame bytes)
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KKTRequestData(pub Vec<u8>);
+
+/// KKT response frame data (serialized KKTFrame bytes)
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KKTResponseData(pub Vec<u8>);
+
+/// Packet forwarding request with embedded inner LP packet
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ForwardPacketData {
+    /// Target gateway's Ed25519 identity (32 bytes)
+    pub target_gateway_identity: [u8; 32],
+
+    /// Target gateway's LP address (IP:port string)
+    pub target_lp_address: String,
+
+    /// Complete inner LP packet bytes (serialized LpPacket)
+    /// This is the CLIENT→EXIT gateway packet, encrypted for exit
+    pub inner_packet_bytes: Vec<u8>,
+}
+
+/// Subsession KK1 message - first message of Noise KK handshake
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SubsessionKK1Data {
+    /// Noise KK first message payload (ephemeral key + encrypted static)
+    pub payload: Vec<u8>,
+}
+
+/// Subsession KK2 message - second message of Noise KK handshake
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SubsessionKK2Data {
+    /// Noise KK second message payload (ephemeral key + encrypted response)
+    pub payload: Vec<u8>,
+}
+
+/// Subsession ready confirmation with new session index
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SubsessionReadyData {
+    /// New subsession's receiver index for routing
+    pub receiver_index: u32,
+}
+
+#[derive(Debug, Clone)]
+pub enum LpMessage {
+    Busy,
+    Handshake(HandshakeData),
+    EncryptedData(EncryptedDataPayload),
+    ClientHello(ClientHelloData),
+    KKTRequest(KKTRequestData),
+    KKTResponse(KKTResponseData),
+    ForwardPacket(ForwardPacketData),
+    /// Receiver index collision - client should retry with new receiver_index
+    Collision,
+    /// Acknowledgment - gateway confirms receipt of message
+    Ack,
+    /// Subsession request - client initiates subsession creation (empty, signal only)
+    SubsessionRequest,
+    /// Subsession KK1 - first message of Noise KK handshake
+    SubsessionKK1(SubsessionKK1Data),
+    /// Subsession KK2 - second message of Noise KK handshake
+    SubsessionKK2(SubsessionKK2Data),
+    /// Subsession ready - subsession established confirmation
+    SubsessionReady(SubsessionReadyData),
+    /// Subsession abort - race winner tells loser to become responder (empty, signal only)
+    SubsessionAbort,
+}
+
+impl Display for LpMessage {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            LpMessage::Busy => write!(f, "Busy"),
+            LpMessage::Handshake(_) => write!(f, "Handshake"),
+            LpMessage::EncryptedData(_) => write!(f, "EncryptedData"),
+            LpMessage::ClientHello(_) => write!(f, "ClientHello"),
+            LpMessage::KKTRequest(_) => write!(f, "KKTRequest"),
+            LpMessage::KKTResponse(_) => write!(f, "KKTResponse"),
+            LpMessage::ForwardPacket(_) => write!(f, "ForwardPacket"),
+            LpMessage::Collision => write!(f, "Collision"),
+            LpMessage::Ack => write!(f, "Ack"),
+            LpMessage::SubsessionRequest => write!(f, "SubsessionRequest"),
+            LpMessage::SubsessionKK1(_) => write!(f, "SubsessionKK1"),
+            LpMessage::SubsessionKK2(_) => write!(f, "SubsessionKK2"),
+            LpMessage::SubsessionReady(_) => write!(f, "SubsessionReady"),
+            LpMessage::SubsessionAbort => write!(f, "SubsessionAbort"),
+        }
+    }
+}
+
+impl LpMessage {
+    pub fn payload(&self) -> &[u8] {
+        match self {
+            LpMessage::Busy => &[],
+            LpMessage::Handshake(payload) => payload.0.as_slice(),
+            LpMessage::EncryptedData(payload) => payload.0.as_slice(),
+            LpMessage::ClientHello(_) => &[], // Structured data, serialized in encode_content
+            LpMessage::KKTRequest(payload) => payload.0.as_slice(),
+            LpMessage::KKTResponse(payload) => payload.0.as_slice(),
+            LpMessage::ForwardPacket(_) => &[], // Structured data, serialized in encode_content
+            LpMessage::Collision => &[],
+            LpMessage::Ack => &[],
+            LpMessage::SubsessionRequest => &[],
+            LpMessage::SubsessionKK1(_) => &[], // Structured data, serialized in encode_content
+            LpMessage::SubsessionKK2(_) => &[], // Structured data, serialized in encode_content
+            LpMessage::SubsessionReady(_) => &[], // Structured data, serialized in encode_content
+            LpMessage::SubsessionAbort => &[],
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        match self {
+            LpMessage::Busy => true,
+            LpMessage::Handshake(payload) => payload.0.is_empty(),
+            LpMessage::EncryptedData(payload) => payload.0.is_empty(),
+            LpMessage::ClientHello(_) => false, // Always has data
+            LpMessage::KKTRequest(payload) => payload.0.is_empty(),
+            LpMessage::KKTResponse(payload) => payload.0.is_empty(),
+            LpMessage::ForwardPacket(_) => false, // Always has data
+            LpMessage::Collision => true,
+            LpMessage::Ack => true,
+            LpMessage::SubsessionRequest => true, // Empty signal
+            LpMessage::SubsessionKK1(_) => false, // Always has payload
+            LpMessage::SubsessionKK2(_) => false, // Always has payload
+            LpMessage::SubsessionReady(_) => false, // Always has receiver_index
+            LpMessage::SubsessionAbort => true,   // Empty signal
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        match self {
+            LpMessage::Busy => 0,
+            LpMessage::Handshake(payload) => payload.0.len(),
+            LpMessage::EncryptedData(payload) => payload.0.len(),
+            // 4 bytes receiver_index + 32 bytes x25519 key + 32 bytes ed25519 key + 32 bytes salt + bincode overhead
+            LpMessage::ClientHello(_) => 101,
+            LpMessage::KKTRequest(payload) => payload.0.len(),
+            LpMessage::KKTResponse(payload) => payload.0.len(),
+            LpMessage::ForwardPacket(data) => {
+                32 + data.target_lp_address.len() + data.inner_packet_bytes.len() + 10
+            }
+            LpMessage::Collision => 0,
+            LpMessage::Ack => 0,
+            LpMessage::SubsessionRequest => 0,
+            // Variable length: bincode overhead (~8 bytes for Vec length) + payload
+            LpMessage::SubsessionKK1(data) => 8 + data.payload.len(),
+            LpMessage::SubsessionKK2(data) => 8 + data.payload.len(),
+            // 4 bytes u32 + bincode overhead (~4 bytes)
+            LpMessage::SubsessionReady(_) => 8,
+            LpMessage::SubsessionAbort => 0,
+        }
+    }
+
+    pub fn typ(&self) -> MessageType {
+        match self {
+            LpMessage::Busy => MessageType::Busy,
+            LpMessage::Handshake(_) => MessageType::Handshake,
+            LpMessage::EncryptedData(_) => MessageType::EncryptedData,
+            LpMessage::ClientHello(_) => MessageType::ClientHello,
+            LpMessage::KKTRequest(_) => MessageType::KKTRequest,
+            LpMessage::KKTResponse(_) => MessageType::KKTResponse,
+            LpMessage::ForwardPacket(_) => MessageType::ForwardPacket,
+            LpMessage::Collision => MessageType::Collision,
+            LpMessage::Ack => MessageType::Ack,
+            LpMessage::SubsessionRequest => MessageType::SubsessionRequest,
+            LpMessage::SubsessionKK1(_) => MessageType::SubsessionKK1,
+            LpMessage::SubsessionKK2(_) => MessageType::SubsessionKK2,
+            LpMessage::SubsessionReady(_) => MessageType::SubsessionReady,
+            LpMessage::SubsessionAbort => MessageType::SubsessionAbort,
+        }
+    }
+
+    pub fn encode_content(&self, dst: &mut BytesMut) {
+        match self {
+            LpMessage::Busy => { /* No content */ }
+            LpMessage::Handshake(payload) => {
+                dst.put_slice(&payload.0);
+            }
+            LpMessage::EncryptedData(payload) => {
+                dst.put_slice(&payload.0);
+            }
+            LpMessage::ClientHello(data) => {
+                // Serialize ClientHelloData using bincode
+                let serialized =
+                    bincode::serialize(data).expect("Failed to serialize ClientHelloData");
+                dst.put_slice(&serialized);
+            }
+            LpMessage::KKTRequest(payload) => {
+                dst.put_slice(&payload.0);
+            }
+            LpMessage::KKTResponse(payload) => {
+                dst.put_slice(&payload.0);
+            }
+            LpMessage::ForwardPacket(data) => {
+                let serialized =
+                    bincode::serialize(data).expect("Failed to serialize ForwardPacketData");
+                dst.put_slice(&serialized);
+            }
+            LpMessage::Collision => { /* No content */ }
+            LpMessage::Ack => { /* No content */ }
+            LpMessage::SubsessionRequest => { /* No content - signal only */ }
+            LpMessage::SubsessionKK1(data) => {
+                let serialized =
+                    bincode::serialize(data).expect("Failed to serialize SubsessionKK1Data");
+                dst.put_slice(&serialized);
+            }
+            LpMessage::SubsessionKK2(data) => {
+                let serialized =
+                    bincode::serialize(data).expect("Failed to serialize SubsessionKK2Data");
+                dst.put_slice(&serialized);
+            }
+            LpMessage::SubsessionReady(data) => {
+                let serialized =
+                    bincode::serialize(data).expect("Failed to serialize SubsessionReadyData");
+                dst.put_slice(&serialized);
+            }
+            LpMessage::SubsessionAbort => { /* No content - signal only */ }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::LpPacket;
+    use crate::packet::{LpHeader, TRAILER_LEN};
+
+    #[test]
+    fn encoding() {
+        let message = LpMessage::EncryptedData(EncryptedDataPayload(vec![11u8; 124]));
+
+        let resp_header = LpHeader {
+            protocol_version: 1,
+            reserved: 0,
+            receiver_idx: 0,
+            counter: 0,
+        };
+
+        let packet = LpPacket {
+            header: resp_header,
+            message,
+            trailer: [80; TRAILER_LEN],
+        };
+
+        // Just print packet for debug, will be captured in test output
+        println!("{packet:?}");
+
+        // Verify message type
+        assert!(matches!(packet.message.typ(), MessageType::EncryptedData));
+
+        // Verify correct data in message
+        match &packet.message {
+            LpMessage::EncryptedData(data) => {
+                assert_eq!(*data, EncryptedDataPayload(vec![11u8; 124]));
+            }
+            _ => panic!("Wrong message type"),
+        }
+    }
+
+    #[test]
+    fn test_client_hello_salt_generation() {
+        let client_key = [1u8; 32];
+        let client_ed25519_key = [2u8; 32];
+        let hello1 = ClientHelloData::new_with_fresh_salt(client_key, client_ed25519_key);
+        let hello2 = ClientHelloData::new_with_fresh_salt(client_key, client_ed25519_key);
+
+        // Different salts should be generated
+        assert_ne!(hello1.salt, hello2.salt);
+
+        // But timestamps should be very close (within 1 second)
+        let ts1 = hello1.extract_timestamp();
+        let ts2 = hello2.extract_timestamp();
+        assert!((ts1 as i64 - ts2 as i64).abs() <= 1);
+    }
+
+    #[test]
+    fn test_client_hello_timestamp_extraction() {
+        let client_key = [2u8; 32];
+        let client_ed25519_key = [3u8; 32];
+        let hello = ClientHelloData::new_with_fresh_salt(client_key, client_ed25519_key);
+
+        let timestamp = hello.extract_timestamp();
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_secs();
+
+        // Timestamp should be within 1 second of now
+        assert!((timestamp as i64 - now as i64).abs() <= 1);
+    }
+
+    #[test]
+    fn test_client_hello_salt_format() {
+        let client_key = [3u8; 32];
+        let client_ed25519_key = [4u8; 32];
+        let hello = ClientHelloData::new_with_fresh_salt(client_key, client_ed25519_key);
+
+        // First 8 bytes should be non-zero timestamp
+        let timestamp_bytes = &hello.salt[..8];
+        assert_ne!(timestamp_bytes, &[0u8; 8]);
+
+        // Salt should be 32 bytes total
+        assert_eq!(hello.salt.len(), 32);
+    }
+}
@@ -0,0 +1,330 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Sans-IO Noise protocol state machine, adapted from noise-psq.
+
+use snow::{TransportState, params::NoiseParams};
+use thiserror::Error;
+
+// --- Error Definition ---
+
+/// Errors related to the Noise protocol state machine.
+#[derive(Error, Debug)]
+pub enum NoiseError {
+    #[error("encountered a Noise decryption error")]
+    DecryptionError,
+
+    #[error("encountered a Noise Protocol error - {0}")]
+    ProtocolError(snow::Error),
+
+    #[error("operation is invalid in the current protocol state")]
+    IncorrectStateError,
+
+    #[error("attempted transport mode operation without real PSK injection")]
+    PskNotInjected,
+
+    #[error("Other Noise-related error: {0}")]
+    Other(String),
+
+    #[error("session is read-only after demotion")]
+    SessionReadOnly,
+}
+
+impl From<snow::Error> for NoiseError {
+    fn from(err: snow::Error) -> Self {
+        match err {
+            snow::Error::Decrypt => NoiseError::DecryptionError,
+            err => NoiseError::ProtocolError(err),
+        }
+    }
+}
+
+// --- Protocol State and Structs ---
+
+/// Represents the possible states of the Noise protocol machine.
+#[derive(Debug)]
+pub enum NoiseProtocolState {
+    /// The protocol is currently performing the handshake.
+    /// Contains the Snow handshake state.
+    Handshaking(Box<snow::HandshakeState>),
+
+    /// The handshake is complete, and the protocol is in transport mode.
+    /// Contains the Snow transport state.
+    Transport(TransportState),
+
+    /// The protocol has encountered an unrecoverable error.
+    /// Stores the error description.
+    Failed(String),
+}
+
+/// The core sans-io Noise protocol state machine.
+#[derive(Debug)]
+pub struct NoiseProtocol {
+    state: NoiseProtocolState,
+    // We might need buffers for incoming/outgoing data later if we add internal buffering
+    // read_buffer: Vec<u8>,
+    // write_buffer: Vec<u8>,
+}
+
+/// Represents the outcome of processing received bytes via `read_message`.
+#[derive(Debug, PartialEq)]
+pub enum ReadResult {
+    /// A handshake or transport message was successfully processed, but yielded no application data
+    /// and did not complete the handshake.
+    NoOp,
+    /// A complete application data message was decrypted.
+    DecryptedData(Vec<u8>),
+    /// The handshake successfully completed during this read operation.
+    HandshakeComplete,
+    // NOTE: NeedMoreBytes variant removed as read_message expects full frames.
+}
+
+// --- Implementation ---
+
+impl NoiseProtocol {
+    /// Creates a new `NoiseProtocol` instance in the Handshaking state.
+    ///
+    /// Takes an initialized `snow::HandshakeState` (e.g., from `snow::Builder`).
+    pub fn new(initial_state: snow::HandshakeState) -> Self {
+        NoiseProtocol {
+            state: NoiseProtocolState::Handshaking(Box::new(initial_state)),
+        }
+    }
+
+    /// Processes a single, complete incoming Noise message frame.
+    ///
+    /// Assumes the caller handles buffering and framing to provide one full message.
+    /// Returns the result of processing the message.
+    pub fn read_message(&mut self, input: &[u8]) -> Result<ReadResult, NoiseError> {
+        // Allocate a buffer large enough for the maximum possible Noise message size.
+        // TODO: Consider reusing a buffer for efficiency.
+        let mut buffer = vec![0u8; 65535]; // Max Noise message size
+
+        match &mut self.state {
+            NoiseProtocolState::Handshaking(handshake_state) => {
+                match handshake_state.read_message(input, &mut buffer) {
+                    Ok(_) => {
+                        if handshake_state.is_handshake_finished() {
+                            // Transition to Transport state.
+                            let current_state = std::mem::replace(
+                                &mut self.state,
+                                // Temporary placeholder needed for mem::replace
+                                NoiseProtocolState::Failed(
+                                    NoiseError::IncorrectStateError.to_string(),
+                                ),
+                            );
+                            if let NoiseProtocolState::Handshaking(state_to_convert) = current_state
+                            {
+                                match state_to_convert.into_transport_mode() {
+                                    Ok(transport_state) => {
+                                        self.state = NoiseProtocolState::Transport(transport_state);
+                                        Ok(ReadResult::HandshakeComplete)
+                                    }
+                                    Err(e) => {
+                                        let err = NoiseError::from(e);
+                                        self.state = NoiseProtocolState::Failed(err.to_string());
+                                        Err(err)
+                                    }
+                                }
+                            } else {
+                                // Should be unreachable
+                                let err = NoiseError::IncorrectStateError;
+                                self.state = NoiseProtocolState::Failed(err.to_string());
+                                Err(err)
+                            }
+                        } else {
+                            // Handshake continues
+                            Ok(ReadResult::NoOp)
+                        }
+                    }
+                    Err(e) => {
+                        let err = NoiseError::from(e);
+                        self.state = NoiseProtocolState::Failed(err.to_string());
+                        Err(err)
+                    }
+                }
+            }
+            NoiseProtocolState::Transport(transport_state) => {
+                match transport_state.read_message(input, &mut buffer) {
+                    Ok(len) => Ok(ReadResult::DecryptedData(buffer[..len].to_vec())),
+                    Err(e) => {
+                        let err = NoiseError::from(e);
+                        self.state = NoiseProtocolState::Failed(err.to_string());
+                        Err(err)
+                    }
+                }
+            }
+            NoiseProtocolState::Failed(_) => Err(NoiseError::IncorrectStateError),
+        }
+    }
+
+    /// Checks if there are pending handshake messages to send.
+    ///
+    /// If in Handshaking state and it's our turn, generates the message.
+    /// Transitions state to Transport if the handshake completes after this message.
+    /// Returns `None` if not in Handshaking state or not our turn.
+    pub fn get_bytes_to_send(&mut self) -> Option<Result<Vec<u8>, NoiseError>> {
+        match &mut self.state {
+            NoiseProtocolState::Handshaking(handshake_state) => {
+                if handshake_state.is_my_turn() {
+                    let mut buffer = vec![0u8; 65535];
+                    match handshake_state.write_message(&[], &mut buffer) {
+                        // Empty payload for handshake msg
+                        Ok(len) => {
+                            if handshake_state.is_handshake_finished() {
+                                // Transition to Transport state.
+                                let current_state = std::mem::replace(
+                                    &mut self.state,
+                                    NoiseProtocolState::Failed(
+                                        NoiseError::IncorrectStateError.to_string(),
+                                    ),
+                                );
+                                if let NoiseProtocolState::Handshaking(state_to_convert) =
+                                    current_state
+                                {
+                                    match state_to_convert.into_transport_mode() {
+                                        Ok(transport_state) => {
+                                            self.state =
+                                                NoiseProtocolState::Transport(transport_state);
+                                            Some(Ok(buffer[..len].to_vec())) // Return final handshake msg
+                                        }
+                                        Err(e) => {
+                                            let err = NoiseError::from(e);
+                                            self.state =
+                                                NoiseProtocolState::Failed(err.to_string());
+                                            Some(Err(err))
+                                        }
+                                    }
+                                } else {
+                                    // Should be unreachable
+                                    let err = NoiseError::IncorrectStateError;
+                                    self.state = NoiseProtocolState::Failed(err.to_string());
+                                    Some(Err(err))
+                                }
+                            } else {
+                                // Handshake continues
+                                Some(Ok(buffer[..len].to_vec()))
+                            }
+                        }
+                        Err(e) => {
+                            let err = NoiseError::from(e);
+                            self.state = NoiseProtocolState::Failed(err.to_string());
+                            Some(Err(err))
+                        }
+                    }
+                } else {
+                    // Not our turn
+                    None
+                }
+            }
+            NoiseProtocolState::Transport(_) | NoiseProtocolState::Failed(_) => {
+                // No handshake messages to send in these states
+                None
+            }
+        }
+    }
+
+    /// Encrypts an application data payload for sending during the Transport phase.
+    ///
+    /// Returns the ciphertext (payload + 16-byte tag).
+    /// Errors if not in Transport state or encryption fails.
+    pub fn write_message(&mut self, payload: &[u8]) -> Result<Vec<u8>, NoiseError> {
+        match &mut self.state {
+            NoiseProtocolState::Transport(transport_state) => {
+                let mut buffer = vec![0u8; payload.len() + 16]; // Payload + tag
+                match transport_state.write_message(payload, &mut buffer) {
+                    Ok(len) => Ok(buffer[..len].to_vec()),
+                    Err(e) => {
+                        let err = NoiseError::from(e);
+                        self.state = NoiseProtocolState::Failed(err.to_string());
+                        Err(err)
+                    }
+                }
+            }
+            NoiseProtocolState::Handshaking(_) | NoiseProtocolState::Failed(_) => {
+                Err(NoiseError::IncorrectStateError)
+            }
+        }
+    }
+
+    /// Returns true if the protocol is in the transport phase (handshake complete).
+    pub fn is_transport(&self) -> bool {
+        matches!(self.state, NoiseProtocolState::Transport(_))
+    }
+
+    /// Returns true if the protocol has failed.
+    pub fn is_failed(&self) -> bool {
+        matches!(self.state, NoiseProtocolState::Failed(_))
+    }
+
+    /// Check if the handshake has finished and the protocol is in transport mode.
+    pub fn is_handshake_finished(&self) -> bool {
+        matches!(self.state, NoiseProtocolState::Transport(_))
+    }
+
+    /// Inject a PSK into the Noise HandshakeState.
+    ///
+    /// This allows dynamic PSK injection after HandshakeState construction,
+    /// which is required for PSQ (Post-Quantum Secure PSK) integration where
+    /// the PSK is derived during the handshake process.
+    ///
+    /// # Arguments
+    /// * `index` - PSK index (typically 3 for XKpsk3 pattern)
+    /// * `psk` - The pre-shared key bytes to inject
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - Not in handshake state
+    /// - The underlying snow library rejects the PSK
+    pub fn set_psk(&mut self, index: u8, psk: &[u8]) -> Result<(), NoiseError> {
+        match &mut self.state {
+            NoiseProtocolState::Handshaking(handshake_state) => {
+                handshake_state
+                    .set_psk(index as usize, psk)
+                    .map_err(NoiseError::ProtocolError)?;
+                Ok(())
+            }
+            _ => Err(NoiseError::IncorrectStateError),
+        }
+    }
+}
+
+pub fn create_noise_state(
+    local_private_key: &[u8],
+    remote_public_key: &[u8],
+    psk: &[u8],
+) -> Result<NoiseProtocol, NoiseError> {
+    let pattern_name = "Noise_XKpsk3_25519_ChaChaPoly_SHA256";
+    let psk_index = 3;
+    let noise_params: NoiseParams = pattern_name.parse().unwrap();
+
+    let builder = snow::Builder::new(noise_params.clone());
+    // Using dummy remote key as it's not needed for state creation itself
+    // In a real scenario, the key would depend on initiator/responder role
+    let handshake_state = builder
+        .local_private_key(local_private_key)
+        .remote_public_key(remote_public_key) // Use own public as dummy remote
+        .psk(psk_index, psk)
+        .build_initiator()?;
+    Ok(NoiseProtocol::new(handshake_state))
+}
+
+pub fn create_noise_state_responder(
+    local_private_key: &[u8],
+    remote_public_key: &[u8],
+    psk: &[u8],
+) -> Result<NoiseProtocol, NoiseError> {
+    let pattern_name = "Noise_XKpsk3_25519_ChaChaPoly_SHA256";
+    let psk_index = 3;
+    let noise_params: NoiseParams = pattern_name.parse().unwrap();
+
+    let builder = snow::Builder::new(noise_params.clone());
+    // Using dummy remote key as it's not needed for state creation itself
+    // In a real scenario, the key would depend on initiator/responder role
+    let handshake_state = builder
+        .local_private_key(local_private_key)
+        .remote_public_key(remote_public_key) // Use own public as dummy remote
+        .psk(psk_index, psk)
+        .build_responder()?;
+    Ok(NoiseProtocol::new(handshake_state))
+}
@@ -0,0 +1,258 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::LpError;
+use crate::message::LpMessage;
+use crate::replay::ReceivingKeyCounterValidator;
+use bytes::{BufMut, BytesMut};
+use nym_lp_common::format_debug_bytes;
+use parking_lot::Mutex;
+use std::fmt::Write;
+use std::fmt::{Debug, Formatter};
+use std::sync::Arc;
+
+#[allow(dead_code)]
+pub(crate) const UDP_HEADER_LEN: usize = 8;
+#[allow(dead_code)]
+pub(crate) const IP_HEADER_LEN: usize = 40; // v4 - 20, v6 - 40
+#[allow(dead_code)]
+pub(crate) const MTU: usize = 1500;
+#[allow(dead_code)]
+pub(crate) const UDP_OVERHEAD: usize = UDP_HEADER_LEN + IP_HEADER_LEN;
+
+#[allow(dead_code)]
+pub const TRAILER_LEN: usize = 16;
+#[allow(dead_code)]
+pub(crate) const UDP_PAYLOAD_SIZE: usize = MTU - UDP_OVERHEAD - TRAILER_LEN;
+
+#[derive(Clone)]
+pub struct LpPacket {
+    pub(crate) header: LpHeader,
+    pub(crate) message: LpMessage,
+    pub(crate) trailer: [u8; TRAILER_LEN],
+}
+
+impl Debug for LpPacket {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", format_debug_bytes(&self.debug_bytes())?)
+    }
+}
+
+impl LpPacket {
+    pub fn new(header: LpHeader, message: LpMessage) -> Self {
+        Self {
+            header,
+            message,
+            trailer: [0; TRAILER_LEN],
+        }
+    }
+
+    /// Compute a hash of the message payload
+    ///
+    /// This can be used for message integrity verification or deduplication
+    pub fn hash_payload(&self) -> [u8; 32] {
+        use sha2::{Digest, Sha256};
+
+        let mut hasher = Sha256::new();
+        let mut buffer = BytesMut::new();
+
+        // Include message type and content in the hash
+        buffer.put_slice(&(self.message.typ() as u16).to_le_bytes());
+        self.message.encode_content(&mut buffer);
+
+        hasher.update(&buffer);
+        hasher.finalize().into()
+    }
+
+    pub fn hash_payload_hex(&self) -> String {
+        let hash = self.hash_payload();
+        hash.iter()
+            .fold(String::with_capacity(hash.len() * 2), |mut acc, byte| {
+                let _ = write!(acc, "{:02x}", byte);
+                acc
+            })
+    }
+
+    pub fn message(&self) -> &LpMessage {
+        &self.message
+    }
+
+    pub fn header(&self) -> &LpHeader {
+        &self.header
+    }
+
+    pub(crate) fn debug_bytes(&self) -> Vec<u8> {
+        let mut bytes = BytesMut::new();
+        self.encode(&mut bytes);
+        bytes.freeze().to_vec()
+    }
+
+    pub(crate) fn encode(&self, dst: &mut BytesMut) {
+        self.header.encode(dst);
+
+        dst.put_slice(&(self.message.typ() as u16).to_le_bytes());
+        self.message.encode_content(dst);
+
+        dst.put_slice(&self.trailer)
+    }
+
+    /// Validate packet counter against a replay protection validator
+    ///
+    /// This performs a quick check to see if the packet counter is valid before
+    /// any expensive processing is done.
+    pub fn validate_counter(
+        &self,
+        validator: &Arc<Mutex<ReceivingKeyCounterValidator>>,
+    ) -> Result<(), LpError> {
+        let guard = validator.lock();
+        guard.will_accept_branchless(self.header.counter)?;
+        Ok(())
+    }
+
+    /// Mark packet as received in the replay protection validator
+    ///
+    /// This should be called after a packet has been successfully processed.
+    pub fn mark_received(
+        &self,
+        validator: &Arc<Mutex<ReceivingKeyCounterValidator>>,
+    ) -> Result<(), LpError> {
+        let mut guard = validator.lock();
+        guard.mark_did_receive_branchless(self.header.counter)?;
+        Ok(())
+    }
+}
+
+/// Session ID used for ClientHello bootstrap packets before session is established.
+///
+/// When a client first connects, it sends a ClientHello packet with receiver_idx=0
+/// because neither side can compute the deterministic session ID yet (requires
+/// both parties' X25519 keys). After ClientHello is processed, both sides derive
+/// the same session ID from their keys, and all subsequent packets use that ID.
+pub const BOOTSTRAP_RECEIVER_IDX: u32 = 0;
+
+/// Outer header (12 bytes) - always cleartext, used for routing.
+///
+/// This is the first 12 bytes of every LP packet, containing only the fields
+/// needed for session lookup (receiver_idx) and replay protection (counter).
+/// For encrypted packets, this is the AAD (additional authenticated data).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OuterHeader {
+    pub receiver_idx: u32,
+    pub counter: u64,
+}
+
+impl OuterHeader {
+    pub const SIZE: usize = 12; // receiver_idx(4) + counter(8)
+
+    pub fn new(receiver_idx: u32, counter: u64) -> Self {
+        Self {
+            receiver_idx,
+            counter,
+        }
+    }
+
+    pub fn parse(src: &[u8]) -> Result<Self, LpError> {
+        if src.len() < Self::SIZE {
+            return Err(LpError::InsufficientBufferSize);
+        }
+        Ok(Self {
+            receiver_idx: u32::from_le_bytes(src[0..4].try_into().unwrap()),
+            counter: u64::from_le_bytes(src[4..12].try_into().unwrap()),
+        })
+    }
+
+    pub fn encode(&self) -> [u8; Self::SIZE] {
+        let mut buf = [0u8; Self::SIZE];
+        buf[0..4].copy_from_slice(&self.receiver_idx.to_le_bytes());
+        buf[4..12].copy_from_slice(&self.counter.to_le_bytes());
+        buf
+    }
+
+    /// Encode directly into a BytesMut buffer
+    pub fn encode_into(&self, dst: &mut BytesMut) {
+        dst.put_slice(&self.receiver_idx.to_le_bytes());
+        dst.put_slice(&self.counter.to_le_bytes());
+    }
+}
+
+/// Internal LP header representation containing all logical header fields.
+///
+/// **Note**: This struct represents the LOGICAL header, not the wire format.
+/// On the wire, packets use the unified format where:
+/// - `OuterHeader` (receiver_idx + counter) always comes first (12 bytes, cleartext)
+/// - Inner content (version + reserved + payload) follows (cleartext or encrypted)
+///
+/// The `LpHeader::encode()` method outputs the old logical format for debug purposes only.
+/// Use `serialize_lp_packet()` in codec.rs for actual wire serialization.
+#[derive(Debug, Clone)]
+pub struct LpHeader {
+    pub protocol_version: u8,
+    pub reserved: u16,
+    pub receiver_idx: u32,
+    pub counter: u64,
+}
+
+impl LpHeader {
+    pub const SIZE: usize = 16;
+}
+
+impl LpHeader {
+    pub fn new(receiver_idx: u32, counter: u64) -> Self {
+        Self {
+            protocol_version: 1,
+            reserved: 0,
+            receiver_idx,
+            counter,
+        }
+    }
+
+    pub fn encode(&self, dst: &mut BytesMut) {
+        // protocol version
+        dst.put_u8(self.protocol_version);
+
+        // reserved
+        dst.put_slice(&[0, 0, 0]);
+
+        // sender index
+        dst.put_slice(&self.receiver_idx.to_le_bytes());
+
+        // counter
+        dst.put_slice(&self.counter.to_le_bytes());
+    }
+
+    pub fn parse(src: &[u8]) -> Result<Self, LpError> {
+        if src.len() < Self::SIZE {
+            return Err(LpError::InsufficientBufferSize);
+        }
+
+        let protocol_version = src[0];
+        // Skip reserved bytes [1..4]
+
+        let mut receiver_idx_bytes = [0u8; 4];
+        receiver_idx_bytes.copy_from_slice(&src[4..8]);
+        let receiver_idx = u32::from_le_bytes(receiver_idx_bytes);
+
+        let mut counter_bytes = [0u8; 8];
+        counter_bytes.copy_from_slice(&src[8..16]);
+        let counter = u64::from_le_bytes(counter_bytes);
+
+        Ok(LpHeader {
+            protocol_version,
+            reserved: 0,
+            receiver_idx,
+            counter,
+        })
+    }
+
+    /// Get the counter value from the header
+    pub fn counter(&self) -> u64 {
+        self.counter
+    }
+
+    /// Get the sender index from the header
+    pub fn receiver_idx(&self) -> u32 {
+        self.receiver_idx
+    }
+}
+
+// subsequent data: MessageType || Data
@@ -0,0 +1,778 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! PSK (Pre-Shared Key) derivation for LP sessions using Blake3 KDF.
+//!
+//! This module implements identity-bound PSK derivation where both client and gateway
+//! derive the same PSK from their LP keypairs.
+//!
+//! Two approaches are supported:
+//! - **Legacy ECDH-only** (`derive_psk`) - Simple but no post-quantum security
+//! - **PSQ-enhanced** (`derive_psk_with_psq_*`) - Combines ECDH with post-quantum KEM
+//!
+//! ## Error Handling Strategy
+//!
+//! **PSQ failures always abort the handshake cleanly with no retry or fallback.**
+//!
+//! ### Rationale
+//!
+//! PSQ errors indicate:
+//! - **Authentication failures** (CredError) - Potential attack or misconfiguration
+//! - **Timing failures** (TimestampElapsed) - Replay attacks or clock skew
+//! - **Crypto failures** (CryptoError) - Library bugs or hardware faults
+//! - **Serialization failures** (Serialization) - Protocol violations or corruption
+//!
+//! None of these are transient errors that benefit from retry. Falling back to
+//! ECDH-only PSK would silently degrade post-quantum security.
+//!
+//! ### Error Recovery Behavior
+//!
+//! On any PSQ error:
+//! 1. Function returns `Err(LpError)` immediately
+//! 2. Session state remains unchanged (dummy PSK, clean Noise state)
+//! 3. Handshake aborts - caller must start fresh connection
+//! 4. Error is logged with diagnostic context
+//!
+//! ### State Guarantees on Error
+//!
+//! - **`psq_state`**: Remains in `NotStarted` (initiator) or `ResponderWaiting` (responder)
+//! - **Noise `HandshakeState`**: PSK slot 3 = dummy `[0u8; 32]` (not modified on error)
+//! - **No partial data**: All allocations are stack-local to failed function
+//! - **No cleanup needed**: No state was mutated
+
+use crate::LpError;
+use crate::keypair::{PrivateKey, PublicKey};
+use libcrux_psq::v1::cred::{Authenticator, Ed25519};
+use libcrux_psq::v1::impls::X25519 as PsqX25519;
+use libcrux_psq::v1::psk_registration::{Initiator, InitiatorMsg, Responder};
+use libcrux_psq::v1::traits::{Ciphertext as PsqCiphertext, PSQ};
+use nym_crypto::asymmetric::ed25519;
+use nym_kkt::ciphersuite::{DecapsulationKey, EncapsulationKey};
+use std::time::Duration;
+use tls_codec::{Deserialize as TlsDeserializeTrait, Serialize as TlsSerializeTrait};
+
+/// Context string for Blake3 KDF domain separation (PSQ-enhanced).
+const PSK_PSQ_CONTEXT: &str = "nym-lp-psk-psq-v1";
+
+/// Session context for PSQ protocol.
+const PSQ_SESSION_CONTEXT: &[u8] = b"nym-lp-psq-session";
+
+/// Context string for subsession PSK derivation.
+const SUBSESSION_PSK_CONTEXT: &str = "lp-subsession-psk-v1";
+
+/// Result from PSQ initiator message creation.
+///
+/// Contains all outputs needed for session establishment:
+/// - `psk`: Final derived PSK for Noise handshake (ECDH || K_pq || salt → Blake3)
+/// - `payload`: Serialized PSQ message to send to responder
+/// - `pq_shared_secret`: Raw K_pq from KEM encapsulation (for subsession derivation)
+#[derive(Debug)]
+pub struct PsqInitiatorResult {
+    /// Final PSK for Noise XKpsk3 handshake
+    pub psk: [u8; 32],
+    /// Serialized PSQ payload to embed in handshake message
+    pub payload: Vec<u8>,
+    /// Raw PQ shared secret (K_pq) before KDF combination.
+    /// Used for deriving subsession PSKs to preserve PQ protection.
+    pub pq_shared_secret: [u8; 32],
+}
+
+/// Result from PSQ responder message processing.
+///
+/// Contains all outputs needed for session establishment:
+/// - `psk`: Final derived PSK for Noise handshake (matches initiator's)
+/// - `psk_handle`: Encrypted PSK handle (ctxt_B) to send back to initiator
+/// - `pq_shared_secret`: Raw K_pq from KEM decapsulation (for subsession derivation)
+#[derive(Debug)]
+pub struct PsqResponderResult {
+    /// Final PSK for Noise XKpsk3 handshake
+    pub psk: [u8; 32],
+    /// Encrypted PSK handle (ctxt_B) from PSQ responder message
+    pub psk_handle: Vec<u8>,
+    /// Raw PQ shared secret (K_pq) before KDF combination.
+    /// Used for deriving subsession PSKs to preserve PQ protection.
+    pub pq_shared_secret: [u8; 32],
+}
+
+/// Derives a PSK using PSQ (Post-Quantum Secure PSK) protocol - Initiator side.
+///
+/// This function combines classical ECDH with post-quantum KEM to provide forward secrecy
+/// and HNDL (Harvest-Now, Decrypt-Later) resistance.
+///
+/// # Formula
+/// ```text
+/// ecdh_secret = ECDH(local_x25519_private, remote_x25519_public)
+/// (psq_psk, ct) = PSQ_Encapsulate(remote_kem_public, session_context)
+/// psk = Blake3_derive_key(
+///     context="nym-lp-psk-psq-v1",
+///     input=ecdh_secret || psq_psk || salt
+/// )
+/// ```
+///
+/// # Arguments
+/// * `local_x25519_private` - Initiator's X25519 private key (for Noise)
+/// * `remote_x25519_public` - Responder's X25519 public key (for Noise)
+/// * `remote_kem_public` - Responder's KEM public key (obtained via KKT)
+/// * `salt` - 32-byte salt for session binding
+///
+/// # Returns
+/// * `Ok((psk, ciphertext))` - PSK and ciphertext to send to responder
+/// * `Err(LpError)` - If PSQ encapsulation fails
+///
+/// # Example
+/// ```ignore
+/// // Client side (after KKT exchange)
+/// let (psk, ciphertext) = derive_psk_with_psq_initiator(
+///     client_x25519_private,
+///     gateway_x25519_public,
+///     &gateway_kem_key,  // from KKT
+///     &salt
+/// )?;
+/// // Send ciphertext to gateway
+/// ```
+pub fn derive_psk_with_psq_initiator(
+    local_x25519_private: &PrivateKey,
+    remote_x25519_public: &PublicKey,
+    remote_kem_public: &EncapsulationKey,
+    salt: &[u8; 32],
+) -> Result<([u8; 32], Vec<u8>), LpError> {
+    // Step 1: Classical ECDH for baseline security
+    let ecdh_secret = local_x25519_private.diffie_hellman(remote_x25519_public);
+
+    // Step 2: PSQ encapsulation for post-quantum security
+    // Extract X25519 public key from EncapsulationKey
+    let kem_pk = match remote_kem_public {
+        EncapsulationKey::X25519(pk) => pk,
+        _ => {
+            return Err(LpError::KKTError(
+                "Only X25519 KEM is currently supported for PSQ".to_string(),
+            ));
+        }
+    };
+
+    let mut rng = rand09::rng();
+    let (psq_psk, ciphertext) =
+        PsqX25519::encapsulate_psq(kem_pk, PSQ_SESSION_CONTEXT, &mut rng)
+            .map_err(|e| LpError::Internal(format!("PSQ encapsulation failed: {:?}", e)))?;
+
+    // Step 3: Combine ECDH + PSQ via Blake3 KDF
+    let mut combined = Vec::with_capacity(64 + psq_psk.len());
+    combined.extend_from_slice(ecdh_secret.as_bytes());
+    combined.extend_from_slice(&psq_psk); // psq_psk is [u8; 32], need &
+    combined.extend_from_slice(salt);
+
+    let final_psk = nym_crypto::kdf::derive_key_blake3(PSK_PSQ_CONTEXT, &combined, &[]);
+
+    // Serialize ciphertext using TLS encoding for transport
+    let ct_bytes = ciphertext
+        .tls_serialize_detached()
+        .map_err(|e| LpError::Internal(format!("Ciphertext serialization failed: {:?}", e)))?;
+
+    Ok((final_psk, ct_bytes))
+}
+
+/// Derives a PSK using PSQ (Post-Quantum Secure PSK) protocol - Responder side.
+///
+/// This function decapsulates the ciphertext from the initiator and combines it with
+/// ECDH to derive the same PSK.
+///
+/// # Formula
+/// ```text
+/// ecdh_secret = ECDH(local_x25519_private, remote_x25519_public)
+/// psq_psk = PSQ_Decapsulate(local_kem_keypair, ciphertext, session_context)
+/// psk = Blake3_derive_key(
+///     context="nym-lp-psk-psq-v1",
+///     input=ecdh_secret || psq_psk || salt
+/// )
+/// ```
+///
+/// # Arguments
+/// * `local_x25519_private` - Responder's X25519 private key (for Noise)
+/// * `remote_x25519_public` - Initiator's X25519 public key (for Noise)
+/// * `local_kem_keypair` - Responder's KEM keypair (decapsulation key, public key)
+/// * `ciphertext` - PSQ ciphertext from initiator
+/// * `salt` - 32-byte salt for session binding
+///
+/// # Returns
+/// * `Ok(psk)` - Derived PSK
+/// * `Err(LpError)` - If PSQ decapsulation fails
+///
+/// # Example
+/// ```ignore
+/// // Gateway side (after receiving ciphertext)
+/// let psk = derive_psk_with_psq_responder(
+///     gateway_x25519_private,
+///     client_x25519_public,
+///     (&gateway_kem_sk, &gateway_kem_pk),
+///     &ciphertext,  // from client
+///     &salt
+/// )?;
+/// ```
+pub fn derive_psk_with_psq_responder(
+    local_x25519_private: &PrivateKey,
+    remote_x25519_public: &PublicKey,
+    local_kem_keypair: (&DecapsulationKey, &EncapsulationKey),
+    ciphertext: &[u8],
+    salt: &[u8; 32],
+) -> Result<[u8; 32], LpError> {
+    // Step 1: Classical ECDH for baseline security
+    let ecdh_secret = local_x25519_private.diffie_hellman(remote_x25519_public);
+
+    // Step 2: Extract X25519 keypair from DecapsulationKey/EncapsulationKey
+    let (kem_sk, kem_pk) = match (local_kem_keypair.0, local_kem_keypair.1) {
+        (DecapsulationKey::X25519(sk), EncapsulationKey::X25519(pk)) => (sk, pk),
+        _ => {
+            return Err(LpError::KKTError(
+                "Only X25519 KEM is currently supported for PSQ".to_string(),
+            ));
+        }
+    };
+
+    // Step 3: Deserialize ciphertext using TLS decoding
+    let ct = PsqCiphertext::<PsqX25519>::tls_deserialize(&mut &ciphertext[..])
+        .map_err(|e| LpError::Internal(format!("Ciphertext deserialization failed: {:?}", e)))?;
+
+    // Step 4: PSQ decapsulation for post-quantum security
+    let psq_psk = PsqX25519::decapsulate_psq(kem_sk, kem_pk, &ct, PSQ_SESSION_CONTEXT)
+        .map_err(|e| LpError::Internal(format!("PSQ decapsulation failed: {:?}", e)))?;
+
+    // Step 5: Combine ECDH + PSQ via Blake3 KDF (same formula as initiator)
+    let mut combined = Vec::with_capacity(64 + psq_psk.len());
+    combined.extend_from_slice(ecdh_secret.as_bytes());
+    combined.extend_from_slice(&psq_psk); // psq_psk is [u8; 32], need &
+    combined.extend_from_slice(salt);
+
+    let final_psk = nym_crypto::kdf::derive_key_blake3(PSK_PSQ_CONTEXT, &combined, &[]);
+
+    Ok(final_psk)
+}
+
+/// PSQ protocol wrapper for initiator (client) side.
+///
+/// Creates a PSQ initiator message with Ed25519 authentication, following the protocol:
+/// 1. Encapsulate PSK using responder's KEM key
+/// 2. Derive PSK and AEAD keys from K_pq
+/// 3. Sign the encapsulation with Ed25519
+/// 4. AEAD encrypt (timestamp || signature || public_key)
+///
+/// Returns (PSK, serialized_payload) where payload includes enc_pq and encrypted auth data.
+///
+/// # Arguments
+/// * `local_x25519_private` - Client's X25519 private key (for hybrid ECDH)
+/// * `remote_x25519_public` - Gateway's X25519 public key (for hybrid ECDH)
+/// * `remote_kem_public` - Gateway's PQ KEM public key (from KKT)
+/// * `client_ed25519_sk` - Client's Ed25519 signing key
+/// * `client_ed25519_pk` - Client's Ed25519 public key (credential)
+/// * `salt` - Session salt
+/// * `session_context` - Context bytes for PSQ (e.g., b"nym-lp-psq-session")
+///
+/// # Returns
+/// `PsqInitiatorResult` containing PSK, payload, and raw PQ shared secret
+pub fn psq_initiator_create_message(
+    local_x25519_private: &PrivateKey,
+    remote_x25519_public: &PublicKey,
+    remote_kem_public: &EncapsulationKey,
+    client_ed25519_sk: &ed25519::PrivateKey,
+    client_ed25519_pk: &ed25519::PublicKey,
+    salt: &[u8; 32],
+    session_context: &[u8],
+) -> Result<PsqInitiatorResult, LpError> {
+    // Step 1: Classical ECDH for baseline security
+    let ecdh_secret = local_x25519_private.diffie_hellman(remote_x25519_public);
+
+    // Step 2: PSQ v1 with Ed25519 authentication
+    // Extract X25519 KEM key from EncapsulationKey
+    let kem_pk = match remote_kem_public {
+        EncapsulationKey::X25519(pk) => pk,
+        _ => {
+            return Err(LpError::KKTError(
+                "Only X25519 KEM is currently supported for PSQ".to_string(),
+            ));
+        }
+    };
+
+    // Convert nym Ed25519 keys to libcrux format
+    type Ed25519VerificationKey = <Ed25519 as Authenticator>::VerificationKey;
+    let ed25519_sk_bytes = client_ed25519_sk.to_bytes();
+    let ed25519_pk_bytes = client_ed25519_pk.to_bytes();
+    let ed25519_verification_key = Ed25519VerificationKey::from_bytes(ed25519_pk_bytes);
+
+    // Use PSQ v1 API with Ed25519 authentication
+    let mut rng = rand09::rng();
+    let (state, initiator_msg) = Initiator::send_initial_message::<Ed25519, PsqX25519>(
+        session_context,
+        Duration::from_secs(3600), // 1 hour expiry
+        kem_pk,
+        &ed25519_sk_bytes,
+        &ed25519_verification_key,
+        &mut rng,
+    )
+    .map_err(|e| {
+        tracing::error!(
+            "PSQ initiator failed - KEM encapsulation or signing error: {:?}",
+            e
+        );
+        LpError::Internal(format!("PSQ v1 send_initial_message failed: {:?}", e))
+    })?;
+
+    // Extract PSQ shared secret (unregistered PSK) - this is K_pq
+    let psq_psk = state.unregistered_psk();
+
+    // pq_shared_secret is the raw K_pq from KEM encapsulation.
+    // Store it for subsession derivation before it's combined with ECDH.
+    let pq_shared_secret: [u8; 32] = *psq_psk;
+
+    // Step 3: Combine ECDH + PSQ via Blake3 KDF
+    let mut combined = Vec::with_capacity(64 + psq_psk.len());
+    combined.extend_from_slice(ecdh_secret.as_bytes());
+    combined.extend_from_slice(psq_psk); // psq_psk is already a &[u8; 32]
+    combined.extend_from_slice(salt);
+
+    let final_psk = nym_crypto::kdf::derive_key_blake3(PSK_PSQ_CONTEXT, &combined, &[]);
+
+    // Serialize InitiatorMsg with TLS encoding for transport
+    let msg_bytes = initiator_msg
+        .tls_serialize_detached()
+        .map_err(|e| LpError::Internal(format!("InitiatorMsg serialization failed: {:?}", e)))?;
+
+    Ok(PsqInitiatorResult {
+        psk: final_psk,
+        payload: msg_bytes,
+        pq_shared_secret,
+    })
+}
+
+/// PSQ protocol wrapper for responder (gateway) side.
+///
+/// Processes a PSQ initiator message, verifies authentication, and derives PSK.
+/// Follows the protocol:
+/// 1. Decapsulate to get K_pq
+/// 2. Derive AEAD keys and verify encrypted auth data
+/// 3. Verify Ed25519 signature
+/// 4. Check timestamp validity
+/// 5. Derive PSK
+///
+/// # Arguments
+/// * `local_x25519_private` - Gateway's X25519 private key (for hybrid ECDH)
+/// * `remote_x25519_public` - Client's X25519 public key (for hybrid ECDH)
+/// * `local_kem_keypair` - Gateway's PQ KEM keypair
+/// * `initiator_ed25519_pk` - Client's Ed25519 public key (for signature verification)
+/// * `psq_payload` - Serialized PSQ payload from initiator
+/// * `salt` - Session salt (must match initiator's)
+/// * `session_context` - Context bytes for PSQ
+///
+/// # Returns
+/// `PsqResponderResult` containing PSK, PSK handle, and raw PQ shared secret
+pub fn psq_responder_process_message(
+    local_x25519_private: &PrivateKey,
+    remote_x25519_public: &PublicKey,
+    local_kem_keypair: (&DecapsulationKey, &EncapsulationKey),
+    initiator_ed25519_pk: &ed25519::PublicKey,
+    psq_payload: &[u8],
+    salt: &[u8; 32],
+    session_context: &[u8],
+) -> Result<PsqResponderResult, LpError> {
+    // Step 1: Classical ECDH for baseline security
+    let ecdh_secret = local_x25519_private.diffie_hellman(remote_x25519_public);
+
+    // Step 2: Extract X25519 keypair from DecapsulationKey/EncapsulationKey
+    let (kem_sk, kem_pk) = match (local_kem_keypair.0, local_kem_keypair.1) {
+        (DecapsulationKey::X25519(sk), EncapsulationKey::X25519(pk)) => (sk, pk),
+        _ => {
+            return Err(LpError::KKTError(
+                "Only X25519 KEM is currently supported for PSQ".to_string(),
+            ));
+        }
+    };
+
+    // Step 3: Deserialize InitiatorMsg using TLS decoding
+    let initiator_msg = InitiatorMsg::<PsqX25519>::tls_deserialize(&mut &psq_payload[..])
+        .map_err(|e| LpError::Internal(format!("InitiatorMsg deserialization failed: {:?}", e)))?;
+
+    // Step 4: Convert nym Ed25519 public key to libcrux VerificationKey format
+    type Ed25519VerificationKey = <Ed25519 as Authenticator>::VerificationKey;
+    let initiator_ed25519_pk_bytes = initiator_ed25519_pk.to_bytes();
+    let initiator_verification_key = Ed25519VerificationKey::from_bytes(initiator_ed25519_pk_bytes);
+
+    // Step 5: PSQ v1 responder processing with Ed25519 verification
+    let (registered_psk, responder_msg) = Responder::send::<Ed25519, PsqX25519>(
+        b"nym-lp-handle",            // PSK storage handle
+        Duration::from_secs(3600),   // 1 hour expiry (must match initiator)
+        session_context,             // Must match initiator's session_context
+        kem_pk,                      // Responder's public key
+        kem_sk,                      // Responder's secret key
+        &initiator_verification_key, // Initiator's Ed25519 public key for verification
+        &initiator_msg,              // InitiatorMsg to verify and process
+    )
+    .map_err(|e| {
+        use libcrux_psq::v1::Error as PsqError;
+        match e {
+            PsqError::CredError => {
+                tracing::warn!(
+                    "PSQ responder auth failure - invalid Ed25519 signature (potential attack)"
+                );
+            }
+            PsqError::TimestampElapsed | PsqError::RegistrationError => {
+                tracing::warn!(
+                    "PSQ responder timing failure - TTL expired (potential replay attack)"
+                );
+            }
+            _ => {
+                tracing::error!("PSQ responder failed - {:?}", e);
+            }
+        }
+        LpError::Internal(format!("PSQ v1 responder send failed: {:?}", e))
+    })?;
+
+    // Extract the PSQ PSK from the registered PSK - this is K_pq
+    let psq_psk = registered_psk.psk;
+
+    // pq_shared_secret is the raw K_pq from KEM decapsulation.
+    // Store it for subsession derivation before it's combined with ECDH.
+    let pq_shared_secret: [u8; 32] = psq_psk;
+
+    // Step 6: Combine ECDH + PSQ via Blake3 KDF (same formula as initiator)
+    let mut combined = Vec::with_capacity(64 + psq_psk.len());
+    combined.extend_from_slice(ecdh_secret.as_bytes());
+    combined.extend_from_slice(&psq_psk); // psq_psk is [u8; 32], need &
+    combined.extend_from_slice(salt);
+
+    let final_psk = nym_crypto::kdf::derive_key_blake3(PSK_PSQ_CONTEXT, &combined, &[]);
+
+    // Step 7: Serialize ResponderMsg (contains ctxt_B - encrypted PSK handle)
+    use tls_codec::Serialize;
+    let responder_msg_bytes = responder_msg
+        .tls_serialize_detached()
+        .map_err(|e| LpError::Internal(format!("ResponderMsg serialization failed: {:?}", e)))?;
+
+    Ok(PsqResponderResult {
+        psk: final_psk,
+        psk_handle: responder_msg_bytes,
+        pq_shared_secret,
+    })
+}
+
+/// Derive subsession PSK from parent's PQ shared secret.
+///
+/// Uses Blake3 KDF with domain separation to derive unique PSK for each subsession.
+/// This preserves PQ protection: subsession keys inherit quantum resistance from
+/// parent's KEM shared secret (K_pq).
+///
+/// # Security Model
+///
+/// Subsessions use Noise KKpsk0 pattern where:
+/// - Both parties already know each other's static X25519 keys (from parent session)
+/// - PSK provides PQ protection by deriving from parent's K_pq
+/// - Each subsession gets unique PSK via index parameter (prevents key reuse)
+///
+/// # Arguments
+/// * `pq_shared_secret` - Parent session's K_pq (32 bytes from KEM)
+/// * `subsession_index` - Monotonic index for this subsession (prevents reuse)
+///
+/// # Returns
+/// 32-byte PSK for Noise KKpsk0 handshake
+pub fn derive_subsession_psk(pq_shared_secret: &[u8; 32], subsession_index: u64) -> [u8; 32] {
+    nym_crypto::kdf::derive_key_blake3(
+        SUBSESSION_PSK_CONTEXT,
+        pq_shared_secret,
+        &subsession_index.to_le_bytes(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::keypair::Keypair;
+
+    #[test]
+    fn test_psk_derivation_is_symmetric() {
+        let keypair_1 = Keypair::default();
+        let keypair_2 = Keypair::default();
+        let salt = [2u8; 32];
+
+        let mut rng = &mut rand09::rng();
+        let (_kem_sk, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+        let dec_key = DecapsulationKey::X25519(_kem_sk);
+
+        // Client derives PSK
+        let (client_psk, ciphertext) = derive_psk_with_psq_initiator(
+            keypair_1.private_key(),
+            keypair_2.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        // Gateway derives PSK from their perspective
+        let gateway_psk = derive_psk_with_psq_responder(
+            keypair_2.private_key(),
+            keypair_1.public_key(),
+            (&dec_key, &enc_key),
+            &ciphertext,
+            &salt,
+        )
+        .unwrap();
+
+        assert_eq!(
+            client_psk, gateway_psk,
+            "Both sides should derive identical PSK"
+        );
+    }
+
+    #[test]
+    fn test_different_salts_produce_different_psks() {
+        let keypair_1 = Keypair::default();
+        let keypair_2 = Keypair::default();
+
+        let salt1 = [1u8; 32];
+        let salt2 = [2u8; 32];
+        let mut rng = &mut rand09::rng();
+        let (_kem_sk, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+
+        let psk1 = derive_psk_with_psq_initiator(
+            keypair_1.private_key(),
+            keypair_2.public_key(),
+            &enc_key,
+            &salt1,
+        )
+        .unwrap();
+        let psk2 = derive_psk_with_psq_initiator(
+            keypair_1.private_key(),
+            keypair_2.public_key(),
+            &enc_key,
+            &salt2,
+        )
+        .unwrap();
+
+        assert_ne!(psk1, psk2, "Different salts should produce different PSKs");
+    }
+
+    #[test]
+    fn test_different_keys_produce_different_psks() {
+        let keypair_1 = Keypair::default();
+        let keypair_2 = Keypair::default();
+        let keypair_3 = Keypair::default();
+        let salt = [3u8; 32];
+
+        let mut rng = &mut rand09::rng();
+        let (_kem_sk, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+
+        let psk1 = derive_psk_with_psq_initiator(
+            keypair_1.private_key(),
+            keypair_2.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+        let psk2 = derive_psk_with_psq_initiator(
+            keypair_1.private_key(),
+            keypair_3.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        assert_ne!(
+            psk1, psk2,
+            "Different remote keys should produce different PSKs"
+        );
+    }
+
+    // PSQ-enhanced PSK tests
+    use nym_kkt::ciphersuite::{DecapsulationKey, EncapsulationKey, KEM};
+    use nym_kkt::key_utils::generate_keypair_libcrux;
+
+    #[test]
+    fn test_psq_derivation_deterministic() {
+        let mut rng = rand09::rng();
+
+        // Generate X25519 keypairs for Noise
+        let client_keypair = Keypair::default();
+        let gateway_keypair = Keypair::default();
+
+        // Generate KEM keypair for PSQ
+        let (kem_sk, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+        let dec_key = DecapsulationKey::X25519(kem_sk);
+
+        let salt = [1u8; 32];
+
+        // Derive PSK twice with same inputs (initiator side)
+        let (_psk1, ct1) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        let (_psk2, _ct2) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        // PSKs will be different due to randomness in PSQ, but ciphertexts too
+        // This test verifies the function is deterministic given the SAME ciphertext
+        let psk_responder1 = derive_psk_with_psq_responder(
+            gateway_keypair.private_key(),
+            client_keypair.public_key(),
+            (&dec_key, &enc_key),
+            &ct1,
+            &salt,
+        )
+        .unwrap();
+
+        let psk_responder2 = derive_psk_with_psq_responder(
+            gateway_keypair.private_key(),
+            client_keypair.public_key(),
+            (&dec_key, &enc_key),
+            &ct1, // Same ciphertext
+            &salt,
+        )
+        .unwrap();
+
+        assert_eq!(
+            psk_responder1, psk_responder2,
+            "Same ciphertext should produce same PSK"
+        );
+    }
+
+    #[test]
+    fn test_psq_derivation_symmetric() {
+        let mut rng = rand09::rng();
+
+        // Generate X25519 keypairs for Noise
+        let client_keypair = Keypair::default();
+        let gateway_keypair = Keypair::default();
+
+        // Generate KEM keypair for PSQ
+        let (kem_sk, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+        let dec_key = DecapsulationKey::X25519(kem_sk);
+
+        let salt = [2u8; 32];
+
+        // Client derives PSK (initiator)
+        let (client_psk, ciphertext) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        // Gateway derives PSK from ciphertext (responder)
+        let gateway_psk = derive_psk_with_psq_responder(
+            gateway_keypair.private_key(),
+            client_keypair.public_key(),
+            (&dec_key, &enc_key),
+            &ciphertext,
+            &salt,
+        )
+        .unwrap();
+
+        assert_eq!(
+            client_psk, gateway_psk,
+            "Both sides should derive identical PSK via PSQ"
+        );
+    }
+
+    #[test]
+    fn test_different_kem_keys_different_psk() {
+        let mut rng = rand09::rng();
+
+        let client_keypair = Keypair::default();
+        let gateway_keypair = Keypair::default();
+
+        // Two different KEM keypairs
+        let (_, kem_pk1) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let (_, kem_pk2) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+
+        let enc_key1 = EncapsulationKey::X25519(kem_pk1);
+        let enc_key2 = EncapsulationKey::X25519(kem_pk2);
+
+        let salt = [3u8; 32];
+
+        let (psk1, _) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key1,
+            &salt,
+        )
+        .unwrap();
+
+        let (psk2, _) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key2,
+            &salt,
+        )
+        .unwrap();
+
+        assert_ne!(
+            psk1, psk2,
+            "Different KEM keys should produce different PSKs"
+        );
+    }
+
+    #[test]
+    fn test_psq_psk_output_length() {
+        let mut rng = rand09::rng();
+
+        let client_keypair = Keypair::default();
+        let gateway_keypair = Keypair::default();
+
+        let (_, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+
+        let salt = [4u8; 32];
+
+        let (psk, _) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt,
+        )
+        .unwrap();
+
+        assert_eq!(psk.len(), 32, "PSQ PSK should be exactly 32 bytes");
+    }
+
+    #[test]
+    fn test_psq_different_salts_different_psks() {
+        let mut rng = rand09::rng();
+
+        let client_keypair = Keypair::default();
+        let gateway_keypair = Keypair::default();
+
+        let (_, kem_pk) = generate_keypair_libcrux(&mut rng, KEM::X25519).unwrap();
+        let enc_key = EncapsulationKey::X25519(kem_pk);
+
+        let salt1 = [1u8; 32];
+        let salt2 = [2u8; 32];
+
+        let (psk1, _) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt1,
+        )
+        .unwrap();
+
+        let (psk2, _) = derive_psk_with_psq_initiator(
+            client_keypair.private_key(),
+            gateway_keypair.public_key(),
+            &enc_key,
+            &salt2,
+        )
+        .unwrap();
+
+        assert_ne!(psk1, psk2, "Different salts should produce different PSKs");
+    }
+}
@@ -0,0 +1,64 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Error types for replay protection.
+
+use thiserror::Error;
+
+/// Errors that can occur during replay protection validation.
+#[derive(Debug, Error)]
+pub enum ReplayError {
+    /// The counter value is invalid (e.g., too far in the future)
+    #[error("Invalid counter value")]
+    InvalidCounter,
+
+    /// The packet has already been received (replay attack)
+    #[error("Duplicate counter value")]
+    DuplicateCounter,
+
+    /// The packet is outside the replay window
+    #[error("Packet outside replay window")]
+    OutOfWindow,
+}
+
+/// Result type for replay protection operations
+pub type ReplayResult<T> = Result<T, ReplayError>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::LpError;
+
+    #[test]
+    fn test_replay_error_variants() {
+        let invalid = ReplayError::InvalidCounter;
+        let duplicate = ReplayError::DuplicateCounter;
+        let out_of_window = ReplayError::OutOfWindow;
+
+        assert_eq!(invalid.to_string(), "Invalid counter value");
+        assert_eq!(duplicate.to_string(), "Duplicate counter value");
+        assert_eq!(out_of_window.to_string(), "Packet outside replay window");
+    }
+
+    #[test]
+    fn test_replay_error_conversion() {
+        let replay_error = ReplayError::InvalidCounter;
+        let lp_error: LpError = replay_error.into();
+
+        match lp_error {
+            LpError::Replay(e) => {
+                assert!(matches!(e, ReplayError::InvalidCounter));
+            }
+            _ => panic!("Expected Replay variant"),
+        }
+    }
+
+    #[test]
+    fn test_replay_result() {
+        let ok_result: ReplayResult<()> = Ok(());
+        let err = ReplayError::InvalidCounter;
+
+        assert!(ok_result.is_ok());
+        assert!(matches!(err, ReplayError::InvalidCounter));
+    }
+}
@@ -0,0 +1,15 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Replay protection module for the Lewes Protocol.
+//!
+//! This module implements BoringTun-style replay protection to prevent
+//! replay attacks and ensure packet ordering. It uses a bitmap-based
+//! approach to track received packets and validate their sequence.
+
+pub mod error;
+pub mod simd;
+pub mod validator;
+
+pub use error::ReplayError;
+pub use validator::ReceivingKeyCounterValidator;
@@ -0,0 +1,281 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! ARM NEON implementation of bitmap operations.
+
+use super::BitmapOps;
+
+#[cfg(target_feature = "neon")]
+use std::arch::aarch64::{vceqq_u64, vdupq_n_u64, vgetq_lane_u64, vld1q_u64, vst1q_u64};
+
+/// ARM NEON bitmap operations implementation
+pub struct ArmBitmapOps;
+
+impl BitmapOps for ArmBitmapOps {
+    #[inline(always)]
+    fn clear_words(bitmap: &mut [u64], start_idx: usize, num_words: usize) {
+        debug_assert!(start_idx + num_words <= bitmap.len());
+
+        #[cfg(target_feature = "neon")]
+        unsafe {
+            // Process 2 words at a time with NEON
+            // Safety:
+            // - vdupq_n_u64 is safe to call with any u64 value
+            let zero_vec = vdupq_n_u64(0);
+            let mut idx = start_idx;
+            let end_idx = start_idx + num_words;
+
+            // Process aligned blocks of 2 words
+            while idx + 2 <= end_idx {
+                // Safety:
+                // - bitmap[idx..] is valid for reads/writes of at least 2 u64 words (16 bytes)
+                // - We've validated with the debug_assert that start_idx + num_words <= bitmap.len()
+                // - We check that idx + 2 <= end_idx to ensure we have 2 complete words
+                vst1q_u64(bitmap[idx..].as_mut_ptr(), zero_vec);
+                idx += 2;
+            }
+
+            // Handle remaining words (0 or 1)
+            while idx < end_idx {
+                bitmap[idx] = 0;
+                idx += 1;
+            }
+        }
+
+        #[cfg(not(target_feature = "neon"))]
+        {
+            // Fallback to scalar implementation
+            for i in start_idx..(start_idx + num_words) {
+                bitmap[i] = 0;
+            }
+        }
+    }
+
+    #[inline(always)]
+    fn is_range_zero(bitmap: &[u64], start_idx: usize, num_words: usize) -> bool {
+        debug_assert!(start_idx + num_words <= bitmap.len());
+
+        #[cfg(target_feature = "neon")]
+        unsafe {
+            // Process 2 words at a time with NEON
+            // Safety:
+            // - vdupq_n_u64 is safe to call with any u64 value
+            let zero_vec = vdupq_n_u64(0);
+            let mut idx = start_idx;
+            let end_idx = start_idx + num_words;
+
+            // Process aligned blocks of 2 words
+            while idx + 2 <= end_idx {
+                // Safety:
+                // - bitmap[idx..] is valid for reads of at least 2 u64 words (16 bytes)
+                // - We've validated with the debug_assert that start_idx + num_words <= bitmap.len()
+                // - We check that idx + 2 <= end_idx to ensure we have 2 complete words
+                let data_vec = vld1q_u64(bitmap[idx..].as_ptr());
+
+                // Safety:
+                // - vceqq_u64 is safe when given valid vector values from vld1q_u64 and vdupq_n_u64
+                // - vgetq_lane_u64 is safe with valid indices (0 and 1) for a 2-lane vector
+                let cmp_result = vceqq_u64(data_vec, zero_vec);
+                let mask1 = vgetq_lane_u64(cmp_result, 0);
+                let mask2 = vgetq_lane_u64(cmp_result, 1);
+
+                if (mask1 & mask2) != u64::MAX {
+                    return false;
+                }
+
+                idx += 2;
+            }
+
+            // Handle remaining words (0 or 1)
+            while idx < end_idx {
+                if bitmap[idx] != 0 {
+                    return false;
+                }
+                idx += 1;
+            }
+
+            true
+        }
+
+        #[cfg(not(target_feature = "neon"))]
+        {
+            // Fallback to scalar implementation
+            bitmap[start_idx..(start_idx + num_words)]
+                .iter()
+                .all(|&w| w == 0)
+        }
+    }
+
+    #[inline(always)]
+    fn set_bit(bitmap: &mut [u64], bit_idx: u64) {
+        let word_idx = (bit_idx / 64) as usize;
+        let bit_pos = bit_idx % 64;
+        bitmap[word_idx] |= 1u64 << bit_pos;
+    }
+
+    #[inline(always)]
+    fn clear_bit(bitmap: &mut [u64], bit_idx: u64) {
+        let word_idx = (bit_idx / 64) as usize;
+        let bit_pos = bit_idx % 64;
+        bitmap[word_idx] &= !(1u64 << bit_pos);
+    }
+
+    #[inline(always)]
+    fn check_bit(bitmap: &[u64], bit_idx: u64) -> bool {
+        let word_idx = (bit_idx / 64) as usize;
+        let bit_pos = bit_idx % 64;
+        (bitmap[word_idx] & (1u64 << bit_pos)) != 0
+    }
+}
+
+/// We also implement optimized versions for specific operations that could
+/// benefit from NEON but don't fit the general trait pattern
+///
+/// Atomic operations for the bitmap
+pub mod atomic {
+    #[cfg(target_feature = "neon")]
+    use std::arch::aarch64::{vdupq_n_u64, vld1q_u64, vorrq_u64, vst1q_u64};
+
+    /// Check and set bit, returning the previous state
+    /// This function is not actually atomic! It's just a non-atomic optimization
+    /// For actual atomic operations, the caller must provide proper synchronization
+    #[inline(always)]
+    pub fn check_and_set_bit(bitmap: &mut [u64], bit_idx: u64) -> bool {
+        let word_idx = (bit_idx / 64) as usize;
+        let bit_pos = bit_idx % 64;
+        let mask = 1u64 << bit_pos;
+
+        // Get old value
+        let old_word = bitmap[word_idx];
+
+        // Set bit regardless of current state
+        bitmap[word_idx] |= mask;
+
+        // Return true if bit was already set (duplicate)
+        (old_word & mask) != 0
+    }
+
+    /// Set a range of bits efficiently using NEON
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it:
+    /// - Uses SIMD intrinsics that require the NEON CPU feature to be available
+    /// - Accesses bitmap memory through raw pointers
+    /// - Does not perform bounds checking beyond what's required for SIMD operations
+    ///
+    /// Caller must ensure:
+    /// - The NEON feature is available on the current CPU
+    /// - `bitmap` has sufficient size to hold indices up to `end_bit/64`
+    /// - `start_bit` and `end_bit` are valid bit indices within the bitmap
+    /// - No other thread is concurrently modifying the same memory
+    #[inline(always)]
+    #[cfg(target_feature = "neon")]
+    pub unsafe fn set_bits_range(bitmap: &mut [u64], start_bit: u64, end_bit: u64) {
+        // Process whole words where possible
+        let start_word = (start_bit / 64) as usize;
+        let end_word = (end_bit / 64) as usize;
+
+        if start_word == end_word {
+            // Special case: all bits in the same word
+            let start_mask = u64::MAX << (start_bit % 64);
+            let end_mask = u64::MAX >> (63 - (end_bit % 64));
+            bitmap[start_word] |= start_mask & end_mask;
+            return;
+        }
+
+        // Handle partial words at the beginning and end
+        if start_bit % 64 != 0 {
+            let start_mask = u64::MAX << (start_bit % 64);
+            bitmap[start_word] |= start_mask;
+        }
+
+        if (end_bit + 1) % 64 != 0 {
+            let end_mask = u64::MAX >> (63 - (end_bit % 64));
+            bitmap[end_word] |= end_mask;
+        }
+
+        // Handle complete words in the middle using NEON
+        let first_full_word = if start_bit % 64 == 0 {
+            start_word
+        } else {
+            start_word + 1
+        };
+        let last_full_word = if (end_bit + 1) % 64 == 0 {
+            end_word
+        } else {
+            end_word - 1
+        };
+
+        if first_full_word <= last_full_word {
+            // Use NEON to set words faster
+            // Safety: vdupq_n_u64 is safe to call with any u64 value
+            let ones_vec = unsafe { vdupq_n_u64(u64::MAX) };
+            let mut idx = first_full_word;
+
+            while idx + 2 <= last_full_word + 1 {
+                // Safety:
+                // - bitmap[idx..] is valid for reads/writes of at least 2 u64 words (16 bytes)
+                // - We check that idx + 2 <= last_full_word + 1 to ensure we have 2 complete words
+                unsafe {
+                    let current_vec = vld1q_u64(bitmap[idx..].as_ptr());
+                    // Safety: vorrq_u64 is safe when given valid vector values
+                    let result_vec = vorrq_u64(current_vec, ones_vec);
+                    vst1q_u64(bitmap[idx..].as_mut_ptr(), result_vec);
+                }
+
+                idx += 2;
+            }
+
+            // Handle remaining words
+            while idx <= last_full_word {
+                bitmap[idx] = u64::MAX;
+                idx += 1;
+            }
+        }
+    }
+
+    /// Set a range of bits efficiently (scalar fallback)
+    #[inline(always)]
+    #[cfg(not(target_feature = "neon"))]
+    pub fn set_bits_range(bitmap: &mut [u64], start_bit: u64, end_bit: u64) {
+        // Process whole words where possible
+        let start_word = (start_bit / 64) as usize;
+        let end_word = (end_bit / 64) as usize;
+
+        if start_word == end_word {
+            // Special case: all bits in the same word
+            let start_mask = u64::MAX << (start_bit % 64);
+            let end_mask = u64::MAX >> (63 - (end_bit % 64));
+            bitmap[start_word] |= start_mask & end_mask;
+            return;
+        }
+
+        // Handle partial words at the beginning and end
+        if start_bit % 64 != 0 {
+            let start_mask = u64::MAX << (start_bit % 64);
+            bitmap[start_word] |= start_mask;
+        }
+
+        if (end_bit + 1) % 64 != 0 {
+            let end_mask = u64::MAX >> (63 - (end_bit % 64));
+            bitmap[end_word] |= end_mask;
+        }
+
+        // Handle complete words in the middle
+        let first_full_word = if start_bit % 64 == 0 {
+            start_word
+        } else {
+            start_word + 1
+        };
+        let last_full_word = if (end_bit + 1) % 64 == 0 {
+            end_word
+        } else {
+            end_word - 1
+        };
+
+        for word_idx in first_full_word..=last_full_word {
+            bitmap[word_idx] = u64::MAX;
+        }
+    }
+}
@@ -0,0 +1,71 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! SIMD optimizations for the replay protection bitmap operations.
+//!
+//! This module provides architecture-specific SIMD implementations with a common interface.
+
+// Re-export the appropriate implementation
+#[cfg(target_arch = "x86_64")]
+mod x86;
+#[cfg(target_arch = "x86_64")]
+pub use self::x86::*;
+
+#[cfg(target_arch = "aarch64")]
+mod arm;
+#[cfg(target_arch = "aarch64")]
+pub use self::arm::*;
+
+// Fallback scalar implementation for all other architectures
+#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
+mod scalar;
+#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
+pub use self::scalar::*;
+
+/// Trait defining SIMD operations for bitmap manipulation
+pub trait BitmapOps {
+    /// Clear a range of words in the bitmap
+    fn clear_words(bitmap: &mut [u64], start_idx: usize, num_words: usize);
+
+    /// Check if a range of words in the bitmap is all zeros
+    fn is_range_zero(bitmap: &[u64], start_idx: usize, num_words: usize) -> bool;
+
+    /// Set a specific bit in the bitmap
+    fn set_bit(bitmap: &mut [u64], bit_idx: u64);
+
+    /// Clear a specific bit in the bitmap
+    fn clear_bit(bitmap: &mut [u64], bit_idx: u64);
+
+    /// Check if a specific bit is set in the bitmap
+    fn check_bit(bitmap: &[u64], bit_idx: u64) -> bool;
+}
+
+/// Get the optimal number of words to process in a SIMD operation
+/// for the current architecture
+#[inline(always)]
+pub fn optimal_simd_width() -> usize {
+    // This value is specialized for each architecture in their respective modules
+    OPTIMAL_SIMD_WIDTH
+}
+
+/// Constant indicating the optimal SIMD processing width in number of u64 words
+/// for the current architecture
+#[cfg(target_arch = "x86_64")]
+#[cfg(target_feature = "avx2")]
+pub const OPTIMAL_SIMD_WIDTH: usize = 4; // 256 bits = 4 u64 words
+
+#[cfg(target_arch = "x86_64")]
+#[cfg(all(not(target_feature = "avx2"), target_feature = "sse2"))]
+pub const OPTIMAL_SIMD_WIDTH: usize = 2; // 128 bits = 2 u64 words
+
+#[cfg(target_arch = "aarch64")]
+#[cfg(target_feature = "neon")]
+pub const OPTIMAL_SIMD_WIDTH: usize = 2; // 128 bits = 2 u64 words
+
+// Fallback for non-SIMD platforms or when features aren't available
+#[cfg(not(any(
+    all(target_arch = "x86_64", target_feature = "avx2"),
+    all(target_arch = "x86_64", target_feature = "sse2"),
+    all(target_arch = "aarch64", target_feature = "neon")
+)))]
+pub const OPTIMAL_SIMD_WIDTH: usize = 1; // Scalar fallback
--- a/Show More
+++ b/Show More