AI Ingestion
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.
Synchronous (Blocking)
The request waits for the Ledger to calculate hashes, assign sequence numbers, and commit to the block store.
Returns: {:ok, [Finalized_Updates]} | {:error, reason}
Asynchronous (Non-blocking)
The Ledger performs immediate structural validation and hands the payload to an internal buffer for background commitment.
Returns: :ok | {:error, validation_failure}
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).
| Scenario | Action |
|---|---|
| reported_dt > (now + leeway) | Rejected. Refuses to future-post. |
| reported_dt > now AND < (now + leeway) | Adjusted. Value replaced by current system now. |
| reported_dt <= now | Accepted. Historical backdating is permitted. |
Architectural Note
While historical backdating is allowed for reported_dt, the witnessed_dt is always generated by the Ledger at the moment of commitment. This provides a dual-timeline view: when the event happened in the world, and when the event was locked into the Ledger.
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.
Synchronous (Blocking)
The request waits for the Ledger to calculate hashes, assign sequence numbers, and commit to the block store.
Returns: {:ok, [Finalized_Updates]} | {:error, reason}
Asynchronous (Non-blocking)
The Ledger performs immediate structural validation and hands the payload to an internal buffer for background commitment.
Returns: :ok | {:error, validation_failure}
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).
| Scenario | Action |
|---|---|
| reported_dt > (now + leeway) | Rejected. Refuses to future-post. |
| reported_dt > now AND < (now + leeway) | Adjusted. Value replaced by current system now. |
| reported_dt <= now | Accepted. Historical backdating is permitted. |
Architectural Note
While historical backdating is allowed for reported_dt, the witnessed_dt is always generated by the Ledger at the moment of commitment. This provides a dual-timeline view: when the event happened in the world, and when the event was locked into the Ledger.