Host Setup

The Parallel Ledger is a minimal-dependency state machine designed for multi-decade persistence.

To ensure the integrity across shifting infrastructure cycles, the core protocol remains decoupled from transient OS features. Since 2016, our persistence layer has relied exclusively on standard relational primitives (tables and indexes), ensuring compatibility from PostgreSQL 9.5 through to the current release.

This "boring" foundation provides a stable reference while granting implementers wide latitude to tune the environment to their specific observations and constraints.

Deployment Strategy

The Parallel Ledger requires low-latency access to the storage controller. We support any environment that provides near-native I/O performance:

Resource Allocation & I/O

The Parallel Ledger’s resource footprint is a direct function of your transactional throughput and data retention policies. While surprising workloads run reliably on commodity hardware, mission-critical production environments should prioritize I/O consistency.

• Memory
  The state machine is lean, but PostgreSQL performance benefits significantly from memory available for caching. For high-integrity environments, ECC RAM remains the industry standard to mitigate the risk of memory-level state corruption.
• Storage
  I/O throughput is the primary scaling bottleneck. We recommend Datacenter-grade NVMe paired with XFS or ZFS. These filesystems provide the predictable Write-Ahead Log (WAL) latency required for high-concurrency finality.
• Optimization
  To minimize write amplification, consider aligning your filesystem and database page sizes (typically 8KB). This is particularly effective for high-volume environments where I/O overhead can impact long-term disk endurance.

Database Setup

The Parallel Ledger requires a dedicated PostgreSQL 17+ instance. For the most predictable performance, we recommend colocating the database on the same host to minimize network-induced latency.

The Data Model

The protocol manages its own tables, namespacing, and indexing.

We recommend provisioning an empty database with an owner-level user for the initial boot.

Data is categorized into three distinct functional areas. This separation maintains high performance even as volumes scale.

Performance Baseline

The following settings are derived from our internal benchmarks on 16GB RAM environments. They are intended as a starting point for your own environment-specific tuning.

# Memory
shared_buffers = 4GB
effective_cache_size = 12GB
work_mem = 10MB
maintenance_work_mem = 1GB

# Write-Ahead Log (WAL)
# Prevents I/O spikes during high-volume periods
wal_buffers = 16MB
min_wal_size = 1GB
max_wal_size = 4GB
checkpoint_completion_target = 0.9

# Disk I/O
# Set for SSD/NVMe performance
random_page_cost = 1.1
effective_io_concurrency = 200

Network Setup

The Parallel Ledger is designed for a Zero-Trust network posture. In air-gapped or high-security environments, we recommend a "Deny by Default" firewall policy, routing all external traffic through a dedicated Partner Gateway.

The Gateway & Security Boundary

To maintain state machine integrity, the protocol should not be exposed to public or untrusted networks. A middleware layer (the Gateway) should handle authentication and rate limiting before passing validated updates to the Ledger.

Service Hardening

# Default posture
ufw default deny incoming
ufw default allow outgoing

# Inbound from Trusted Gateway
ufw allow from [GATEWAY_IP] to any port 50051 proto tcp
ufw allow from [GATEWAY_IP] to any port 4000 proto tcp

# Outbound to Partner Relay Node
ufw allow to [PARTNER_NODE_IP] port 443 proto tcp

ufw enable

For environments where TCP/IP exposure must be eliminated entirely, we are currently developing Unix Domain Socket support. This will allow the Gateway and Ledger to communicate via the filesystem, permitting the total disabling of inbound networking on the host.

Runtime Configuration

The Parallel Ledger is distributed as a single, immutable release binary.

To ensure auditability and consistent behavior across diverse environments, the software remains identical for all clients from entry-level implementations to sovereign-tier deployments.

System behavior is governed by a Dual-Key Configuration model:

Licensing & Identity

The Ledger requires a signed cryptographic manifest (license.lic) to initialize the core state machine. This file establishes your Client Identity and hardware-specific performance tiers.

Environment Variables

Feature Flags (GUI)

The following toggles control visibility within the Administrative Web Interface. These do not affect the underlying protocol or API capabilities.

System Health

The Parallel Ledger is designed to be a "good citizen" within your existing infrastructure. We defer complex alerting and visualization to the Partner Gateway or your organization's standard observability stack to ensure the Ledger remains a decoupled, high-integrity state machine.

Monitoring Philosophy

We prioritize raw signal over proprietary dashboards. For this release, we expect operators to monitor the Ledger host using standard systems-level telemetry.

Future Telemetry Roadmap

We are currently evaluating the most efficient method for exposing internal protocol metrics. Our goal is to provide high-resolution data without impacting the performance of the witness relay.

The Gateway Model

The Parallel Ledger is a deterministic state machine, not a general-purpose API. It is designed to operate behind a Partner Gateway. This boundary separates the immutable ledger protocol from your specific business logic and external requirements.

The Functional Boundary

While the Ledger maintains data integrity and cryptographic proofs, the Gateway is where you implement Domain Logic. To ensure the Gateway can match the Ledger's native throughput and concurrency, we require this layer to be built in Elixir/OTP.

Implementation Support

We recognize the requirement for Elixir may represent a shift in your standard stack. To assist with implementation and optimization, we provide weekly on-site engineering sessions in Vancouver.

Downstream Integration

The Elixir requirement applies only to the Gateway (the direct relay to the Ledger). Downstream Extraction Layers—such as analytics engines, reporting tools, or legacy APIs—can be built in any language (Go, Rust, Java, etc.) that supports gRPC or REST.

Status Updates

The Status Update is the atomic unit of the Parallel Ledger.

Every instance details a specific fact for a specific point in time.

%StatusUpdate{
  # The Atomic Trio (Required)
  :context_slug         # Namespace (CLIENT_A_*)
  :slug                 # Entity Identifier
  :code                 # Property (module--property)

  # Payload Values
  :status_dt            # Flexible date/time (ie: ETA)
  :status_int           # Numeric value (boolean/bigint)
  :status_slug          # Flexible slug reference
  :status_text_value    # Description or raw data
  :reported_dt          # Source system reported time
  :executed_by_slug     # Authority that initiated change

  # Audit & Lineage
  :witnessed_dt         # Appliance-assigned seal time
  :property_sequence_no # Property chain position
  :chain_hash           # Cryptographic proof
}

The Atomic Trio

Every update is defined by a composite key trio that uniquely identifies the property being tracked. The protocol uses this trio to chain historical changes and maintain the current state.

Property-Level Chaining

The protocol tracks each code as a discrete stream of facts. If an incoming event contains multiple changes (e.g., an email and a phone number), the Partner Gateway must decompose that event into two separate Status Updates.

Cryptographic Finality

Once a Status Update is accepted by the Ledger, the protocol performs all necessary operations to:

• Sequence: Position the update within the property's historical chain.
• Seal: Generate a cryptographic hash proof for the update.
• Finalize: Commit the state to both the immutable Ledger and the current-state observation table.

Context Management

A context_slug is the fundamental unit of multi-tenancy within The Parallel Ledger. Contexts function as independent data silos, providing physical isolation, cryptographic separation, and dedicated performance allocation.

Syntax & Constraints

Because contexts map directly to database namespaces, they are subject to stricter validation rules than standard entity slugs.

The Global Prefix

To ensure uniqueness across the Witness Relay network, every context must be prefixed with your client_slug using a double-underscore separator.

Architectural Strategy

Treat context creation as an Infrastructure Event. Because the name is part of the cryptographic seal, contexts cannot be renamed once witnessed.

Slug Management

A slug is the unique identifier for an entity within a specific context. It serves as the permanent anchor for all historical status updates related to that subject.

Technical Standards

The "Underscore" Convention

While the Parallel Ledger treats slugs as raw strings, it's important to consider the potential requirements introduced by Partner Gateways and web interfaces.

We strongly recommend a UPPERCASE_UNDERSCORE convention for all slugs, while avoiding most special characters.

The only rigorously tested special characters for slugs are the underscore and dashes. Please note that dashes are not permitted for context slugs due to database limitations.

Anticipating the Future

The Parallel Ledger is designed to be long term architecture. To prevent internal collisions—especially when dealing with common identifiers like Invoice IDs or Serial Numbers—you must ensure your slugs are Overly Specific.

Recommended Patterns

When designing your slugs, consider the following patterns to maximize the "searchability" of your ledger:

• Physical Assets: Use VINs, Serial Numbers, or MAC addresses prefixed by the asset type (e.g., VEHICLE_VIN_12345...).
• Financial Entities: Prefix with the institution and the account type (e.g., SANTANDER_IBAN_ES12...).
• Internal System IDs: If using database primary keys, prefix with the system name (e.g., ERP_PRIMARY_USER_9982).

Code Management

The code is the definitive key for a historical chain of facts. Because the Ledger provides cryptographic finality, a code cannot be renamed or remapped once it is witnessed.

The Module--Property Anchor

The module--property convention is not merely for organization; it is a structural anchor between the Subject (slug) and its Attributes (code).

To prevent data collisions at scale, the module portion must provide enough specificity to describe exactly which sub-domain of the entity is being updated.

Standards for Multi-Decade Sustainability

When defining your codes within the Partner Gateway, adhere to these foundational requirements to avoid irrecoverable technical debt:

Status Update Payloads

The Parallel Ledger uses a fixed-slot schema to store varied data types. Rather than defining a custom table for every business use case, you map your data into the four primitive "status" fields provided by the protocol.

The Data Slots

Each Status Update can utilize any combination of the following four fields. If a property requires multiple types (e.g., a label and a numeric value), they can be sent within the same update.

Permanent vs. Redactable Data

It is critical to distinguish between Status Slugs (system-level labels) and Status Text Values (raw data) when designing your schema.

Authority & Attribution

Beyond the data slots, every update must identify the initiating authority to complete the audit trail.

Inbound Ingestion

The Parallel Ledger provides two primary interfaces for receiving data: a high-performance gRPC stream and a traditional REST API. Both endpoints expect a list of prepared StatusUpdate objects, allowing the Gateway to commit multiple properties across multiple entities in a single atomic request.

Interface Protocols

gRPC (Recommended)

For production workloads, gRPC is the preferred ingestion method. By utilizing Protocol Buffers, we minimize serialization overhead and maintain a strict contract between the Gateway and the Ledger. This is the most efficient path for high-density witnessing.

REST API

A standard JSON-over-HTTP interface is available for environments where gRPC is not feasible. While slightly more verbose, it follows the same validation and commitment logic as the gRPC interface.

Synchronous vs. Asynchronous Commitment

The Gateway can choose its commitment strategy based on the urgency of the response and the nature of the data source.

Temporal Normalization

Timestamps are a frequent source of "Garbage In" scenarios. To accommodate diverse origin systems, status_dt and reported_dt accept the following formats:

• Unix Seconds
• Unix Milliseconds
• Unix Microseconds
• ISO8601 Strings

The Future-Post Guardrail

The Ledger enforces a logical "Now" to prevent chronologically impossible records. Every reported_dt is checked against the system now_dt with a configurable leeway (default: 5 seconds).

Outbound & Observability

The Parallel Ledger provides multiple egress paths for data verification and system health. While the Ledger remains a "protected sink," it offers robust utilities for auditing the integrity of the chain and querying current state for proprietary visualizations.

The Ledger GUI

An administrative interface is available for high-level system health and direct access to auditing utilities. Access to this interface can be restricted via runtime configuration (Password/Basic Auth) to ensure only authorized architects can access the internal state machine.

Bitemporal Time-Stepping

Because the Ledger operates at microsecond precision, simple "before and after" views are often insufficient for complex audits. We provide a Point-in-Time Navigator that allows architects to step through the evolution of an entity property at granular intervals.

Gateway Query Interface

The National Five Partner's Gateway can query the Ledger to populate proprietary dashboards and client-facing visualizations. The query engine is optimized for two primary patterns:

• Current State Materialization: Retrieve the most recent StatusUpdate for any given slug + code pair. This is used to present the "live" status of an entity to end-users.
• Historical Reconstruction: Retrieve a range of updates to visualize trends, verify historical sequences, or generate delta reports for institutional reporting.

Tombstoning Data

The Tombstone operation is the protocol's mechanism for the targeted redaction of sensitive data while maintaining the integrity of the cryptographic chain.

Unlike a standard database DELETE, a Tombstone nullifies specific payload values within existing StatusUpdate records without removing the record's position in the property sequence.

Targeting Logic

Tombstoning leverages the exact same sourcing logic as StatusUpdate.lookup_many. This ensures consistency across the platform: if you can query it, you can tombstone it.

Payload Redaction Rules

The Ledger treats different data types with varying levels of aggression during a Tombstone event to balance privacy with system performance.

Chain Integrity

It is important to note that property_sequence_no and chain_hash remain untouched. The Ledger preserves the "shape" of history—knowing that a change occurred and who witnessed it—while removing the content of the change.

Utilities & Data Portability

The Parallel Ledger is designed to ensure that the "Record of Fact" remains accessible even in the absence of the application binary. We provide a suite of portability utilities to ensure your data never becomes a "black box."

To achieve high-density performance, the underlying PostgreSQL database utilizes aggressive string deduplication and an optimized block structure. While this is ideal for machine-scale witnessing, it makes direct SQL querying complex. Our utility strategy provides the "exit ramp" required for long-term institutional peace of mind.

The Transparency Exit

We recognize that enterprise risk management requires a path to data recovery that does not depend on a proprietary runtime. We are currently evaluating two primary methods for ensuring this transparency:

Direct Database Access

National Five Partners retain full administrative access to the PostgreSQL instance. While the Ledger manages the internal mapping of IDs to strings, the schema remains documented and open. Advanced teams can utilize our provided view definitions to perform direct SQL audits for custom reporting or integration with external BI tools.

The "Cold Start" Guarantee

In the event of a total system failure, the combination of our open database schema and the standalone exporter ensures that the Chain of Integrity can be verified using standard cryptographic libraries (SHA-256). The math remains true, regardless of whether the Ledger binary is running.

Witness Signing & Cryptography

The integrity of the Parallel Ledger is derived from Deterministic Witnessing. Every block is cryptographically signed upon commitment, transforming a sequence of status updates into an immutable, third-party verifiable record.

Our cryptographic implementation prioritizes Boring Reliability. By leveraging OpenSSL as the primary interface for key management and signing operations, we ensure that the Ledger’s security posture remains consistent with global institutional standards.

Signing Tiers & Hardware Trust

The Ledger supports a tiered approach to key storage. This allows National Five Partners to balance deployment velocity with the stringent "Root of Trust" requirements found in highly regulated sectors.

Multi-Key Witnessing

To further mitigate the risk of key compromise, the Ledger supports Parallel Signature Sets. Each block can be configured to be signed by multiple independent keys simultaneously.

OpenSSL Integration

The Ledger does not "roll its own crypto." All signing operations are routed through OpenSSL, ensuring that we benefit from continuous security audits and broad support for diverse cryptographic curves (e.g., Ed25519 or ECDSA).

witness_keys:
  - id: "primary-01"
    type: "software"
    path: "/etc/ledger/keys/primary.pem"
  - id: "hsm-vault-01"
    type: "pkcs11"
    engine: "tpm2"

Witness Relays

The Witness Relay is a high-integrity synchronization protocol designed to provide External Validation of the local Ledger state. By broadcasting cryptographic proofs to remote nodes, you establish a distributed "Proof of Fact" that is independent of any single host.

This mechanism allows National Five Partners to satisfy the most stringent regulatory and institutional requirements by providing real-time, tamper-evident transparency to authorized oversight bodies or secondary partner nodes.

Zero-Data Synchronization

The Relay protocol is engineered for Privacy by Design. It does not transmit client data, status values, or PII (Personally Identifiable Information). Instead, it broadcasts only the structural metadata of the witnessed blocks.

Institutional Compliance

For National Five Partners operating in regulated sectors (such as those governed by the SEC or FINRA), the Witness Relay acts as an automated "Compliance Stream."

• Regulatory Transparency: Provide a dedicated relay feed to a regulator's node, allowing them to verify the chain's integrity without giving them direct database access.
• Cross-Node Consensus: Synchronize proofs across multiple assurance nodes to ensure that no single administrator can modify the historical record across the entire network.
• Tamper Detection: Any discrepancy between the local block hash and the relayed hash triggers an immediate integrity alert, providing sub-second detection of unauthorized data modification.

Tiered Availability

The Witness Relay is an Enterprise-grade feature, designed for deployments where multi-party verification and regulatory oversight are fundamental requirements.

# Example Relay Configuration
relays:
  - id: "finra-audit-node"
    context: "equities-trading"
    endpoint: "https://relay.partner-node.org"
    interval: "real-time"

Verification Protocols