panurus

Network Service

The Network Service (token/services/network) is the bridge layer of Panurus. It provides a consistent, backend-agnostic interface that translates generic token operations into the specific formats and protocols required by the underlying Distributed Ledger Technology (DLT), such as Hyperledger Fabric, FabricX, or Ethereum/EVM.

Overview

The Network Service abstracts the complexities of different ledger implementations, allowing Application Services (like TTX) and Token Drivers to remain agnostic of the specific network backend. This abstraction enables Panurus to support multiple DLT platforms through a pluggable driver architecture.

graph TB
    subgraph "Application Layer"
        TTX[TTX Service]
        Driver[Token Driver]
    end

    subgraph "Network Service (Bridge)"
        NS[Network Service Interface]
        Provider[Network Provider]
    end

    subgraph "Driver Layer"
        FabricD[Fabric Driver]
        FabricXD[FabricX Driver]
        EVMD[EVM Driver]
    end

    subgraph "DLT Backends"
        Fabric[Hyperledger Fabric<br/>with Token Chaincode]
        FabricX[FabricX<br/>with FSC Endorsers]
        EVM[Ethereum/EVM<br/>with FSC Endorsers]
    end

    TTX --> NS
    Driver --> NS
    NS --> Provider
    Provider --> FabricD
    Provider --> FabricXD
    Provider --> EVMD
    FabricD --> Fabric
    FabricXD --> FabricX
    EVMD --> EVM

Driver-Based Architecture

The Network Service uses a driver pattern to enable pluggable backend implementations. This design separates the interface from the implementation, allowing Panurus to support different DLT platforms without changing application code.

Core Components

Network Interface (driver.Network)
- Defines the contract that all network implementations must fulfill
- Provides methods for transaction submission, endorsement, and state queries
- Ensures consistent behavior across different backends
Driver Interface (driver.Driver)
- Factory interface for creating network instances
- Single method: New(network, channel string) (Network, error)
- Enables runtime selection of the appropriate backend
Network Provider (Provider)
- Manages multiple network instances
- Registers and coordinates available drivers
- Provides lazy initialization and caching of network connections

How It Works

sequenceDiagram
    participant App as Application
    participant Provider as Network Provider
    participant Driver as Network Driver
    participant Backend as DLT Backend

    App->>Provider: GetNetwork(network, channel)
    Provider->>Driver: New(network, channel)
    Driver->>Backend: Initialize connection
    Backend-->>Driver: Connection established
    Driver-->>Provider: Network instance
    Provider-->>App: Network instance
    
    App->>Provider: RequestApproval(...)
    Provider->>Backend: Execute via driver
    Backend-->>Provider: Endorsed envelope
    Provider-->>App: Result

Key Benefits:

Pluggability: New backends can be added by implementing the driver interface
Consistency: Applications use the same API regardless of the underlying DLT
Flexibility: Different networks can use different drivers within the same application
Testability: Drivers can be mocked for testing without real network connections

Core Responsibilities

The Network Service is responsible for several critical functions:

1. Request Translation

Translating high-level token requests (e.g., “Transfer 10 tokens from A to B”) into ledger-specific transaction envelopes. Each driver implementation handles the specifics of its target platform.

2. Transaction Submission

Broadcasting endorsed transaction envelopes to the network’s ordering service via Broadcast.

3. Finality Tracking

Monitoring the ledger for transaction commitment. It provides a listener-based API (FinalityListener) that notifies Panurus when a transaction is validated or invalidated. The Network Service also instantiates the Transaction Recovery Service from the Storage Service to handle pending transactions that may have lost their finality listeners.

4. Public Parameters Discovery

Acting as the primary fetcher for the system’s Public Parameters. It monitors the ledger for updates and ensures Panurus is synchronized with the latest cryptographic material.

5. Ledger Querying

Providing a Ledger interface to retrieve the current state of tokens and other relevant ledger data.

Network Interface

The driver.Network interface defines the following key methods:

Name() string - Returns the network identifier
Channel() string - Returns the channel/partition name
Normalize(opt) (*ServiceOptions, error) - Populates default service options from network configuration
Connect(ns) ([]ServiceOption, error) - Initializes the connection to the backend for a namespace
Broadcast(ctx, blob) error - Submits transactions to ordering service
NewEnvelope() Envelope - Creates a new transaction envelope
RequestApproval(...) (Envelope, error) - Requests transaction endorsement
SetupPublicParams(...) (Envelope, error) - Submits new/updated public parameters, including first-time namespace setup
ComputeTxID(*TxID) string - Calculates transaction identifiers
FetchPublicParameters(namespace) ([]byte, error) - Retrieves public parameters
QueryTokens(...) ([][]byte, error) - Queries token state
AreTokensSpent(...) ([]bool, error) - Checks token spent status
LocalMembership() LocalMembership - Returns the local membership service for node identities
AddFinalityListener(...) error - Registers finality notifications
GetTransactionStatus(...) (status, hash, message, error) - Retrieves current status and token request hash for a transaction
LookupTransferMetadataKey(...) ([]byte, error) - Scans the ledger for transfer-action metadata
Ledger() (Ledger, error) - Provides ledger access

Available Implementations

Panurus currently provides network driver implementations for the following platforms:

Hyperledger Fabric

Traditional Fabric network with token chaincode deployed on peers for endorsement and validation.

Documentation: Network Service - Fabric Implementation

Key Features:

Token chaincode handles endorsement logic
Supports both delivery and notification finality modes
Integrates with Fabric’s endorsement policies
Uses Fabric peers for transaction validation

FabricX

Optimized Fabric variant where FSC nodes act as endorsers, eliminating the need for traditional chaincode.

Documentation: Network Service - FabricX Implementation

Key Features:

FSC nodes replace traditional peer endorsers
View-based endorsement protocol
Async finality processing with event queues
Optimized for high-performance scenarios

Ethereum / EVM

Network driver for Ethereum and EVM-compatible blockchains, implemented in x/token/services/network/evm.

The design document describes two architectural approaches; only Approach 2 (Pre-Order Execution with FSC Endorsers) is implemented and shipped today. It supports both the fabtoken and zkatdlog/nogh token drivers.

Documentation:

Network Service - Ethereum Implementation Guide - Architecture, both approaches, and the Approach-2 contract walkthrough
Ethereum Driver Internals - Derivations, invariants, and traps for implementers/debuggers
Ethereum Deployment Runbook - Bootstrapping a TMS with the Approach-2 driver

Key Features (Approach 2, shipped):

FSC endorsers validate off-chain and sign a StateDelta with EIP-712; the chain only checks endorser signatures, public-parameters version, and spend legality
One TokenState clone per TMS; one Ethereum transaction per token request
Speaks plain JSON-RPC (no go-ethereum dependency), so it works against any EVM node (e.g. geth, Besu)
Graph-hiding token drivers are supported by the contracts/translator but none ship yet (fabtoken and zkatdlog/nogh are both graph-revealing)

Key Considerations:

Account-based ledger model vs UTXO
Gas cost optimization strategies
Finality based on consensus mechanism (PoW/PoS)
Smart contract design patterns

Configuration

Each Token Management Service (TMS) must be mapped to a network and channel:

token:
  tms:
    my-tms-id:
      network: my-network-name  # Matches fsc.networks configuration
      channel: my-channel-name
      namespace: my-chaincode-id

The Network Service uses this configuration to:

Select the appropriate driver for the network
Initialize the connection to the specified channel
Configure namespace-specific settings

Driver Registration

Drivers are registered during system initialization:

// Example: Registering a network driver
networkProvider := network.NewProvider(configService)
networkProvider.RegisterDriver(fabricDriver)
networkProvider.RegisterDriver(fabricxDriver)

The provider automatically selects the appropriate driver based on the network configuration when GetNetwork() is called.

Transaction Recovery Integration

The Network Service instantiates and manages the Transaction Recovery Service provided by the Storage Service. This integration ensures that pending transactions are automatically recovered if their finality listeners are lost due to node restarts, network interruptions, or other failures.

Key Integration Points:

Recovery Service Instantiation: The Network Service creates recovery managers with the appropriate transaction database (TTXDB for regular nodes, AuditDB for auditor nodes)
Network-Specific Handlers: Provides network-specific transaction status query capabilities to the recovery handlers
Background Processing: Starts and manages the background recovery process as part of network initialization
Distributed Coordination: Leverages PostgreSQL advisory locks for leader election in multi-instance deployments

For detailed information about the recovery mechanism, see Storage Service - Transaction Recovery.