> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Operating Lerian SILOC

> Operate Lerian SILOC: BACEN settlement windows, ICP-Brasil certificates, MQ-configured SFN processing, durable deduplication, monitoring, alerts, and audit.

SILOC settles on a **deferred-net, business-day** basis. With its SILOC MQ connection configured, the service keeps the gateway connection open and dispatches its supported messages. It holds no accounting position.

## Settlement windows

***

SILOC settles on a deferred multilateral net basis, on business days. Nuclea defines the daily settlement windows for boleto and card products. Lerian SILOC records and applies the transfer-order messages that open, advance, reconcile, and close its cycle state. It does not calculate the monetary net position.

## Regulated certificates

***

You register the gateway's certificates as a **public certificate plus an external custody reference**. The service holds no private key. When you register a certificate, the service parses its subject, serial, and validity window. You revoke the certificate over the API when you retire it. A **credential-disabled** state halts the gateway. A disabled or revoked certificate fail-closes the connection instead of running on invalid credentials.

## Contingency and recovery

***

The SFN ingestion path has defined outcomes under failure. It does not promise to retain every frame. It also does not promise that every operation has a single end-to-end effect:

* Inbound SFN processing starts when you configure the complete SILOC MQ connection descriptor. Without a connection trigger, the service starts without live SILOC connectivity. Setting `MQ_HOST`, `MQ_CHANNEL`, `MQ_QUEUE_MANAGER`, `MQ_SEND_QUEUE`, or `MQ_RECEIVE_QUEUE` triggers validation of the complete descriptor at startup. Providing only part of the descriptor fails closed and prevents the service from starting.
* An undecodable envelope, a decoded message without a nonblank `BCMSG.NUOp`, or an unsupported **(`CodProdt`, `CodMsg`)** pair fails closed to an operator exception. The service supports `PAG0101` for `OT` and `SLC`: it defers participant status. The service does not support `LDL0020` and `LDL0006`, and never relays them as settlement funding.
* A retryable dispatch failure remains unacknowledged. With offset-safe source commits, the service reads it again after a restart from the last committed offset. A persistent transient failure can stall its partition until restart.
* SLC relay is **at-least-once**. For a successfully decoded SLC funding frame, the service checks durable deduplication by **`BCMSG.NUOp`** before relay and writes the processed-message record only after relay succeeds. This is not message-ID-only deduplication and is not an unconditional end-to-end exactly-once guarantee.

## Reconciliation

***

Reconciliation runs at several grains so the connection's state never drifts:

* **Processed-message dedup ledger.** For successfully decoded SLC funding frames with a nonblank NUOp, the ledger uses `BCMSG.NUOp` and records it only after a successful relay. Undecoded and unsupported messages do not receive a processed-message record.
* **Message-processing audit feed.** The audit feed lists supported SFN messages that the service dispatched.
* **Per-participant status and status history.** Each participant carries its operational status. The service keeps every status change as a status-event history entry.

## Monitoring, alerts, and audit

***

Lerian SILOC exposes an operator surface for watching OT settlement cycles, connection and relay health, and participant status. The cycle and reconciliation surfaces report recorded state and reconciliation sets. They do not calculate aggregate position figures on read.

* **OT settlement cycles.** [`GET /api/v1/siloc/cycles`](/en/reference/rails/siloc/list-cycles) and [`GET /api/v1/siloc/cycles/{cycleId}`](/en/reference/rails/siloc/get-cycle) list and inspect cycles. [`GET /api/v1/siloc/cycles/{cycleId}/reconciliation`](/en/reference/rails/siloc/get-cycle-reconciliation) returns the reconciliation result, and [`GET /api/v1/siloc/cycles/{cycleId}/recalculations`](/en/reference/rails/siloc/get-cycle-recalculations) returns the cycle's recálculo round chain, including each round's complement/deposit window closure.
* **Settlement instructions.** [`GET /api/v1/siloc/settlement-instructions`](/en/reference/rails/siloc/list-settlement-instructions) and [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](/en/reference/rails/siloc/get-settlement-instruction) return each cycle's obligation legs. [`POST /api/v1/siloc/rocs`](/en/reference/rails/siloc/ingest-roc) ingests a semantic ROC revision that supersedes prior values for the cycle.
* **Operational alerts.** [`GET /api/v1/siloc/alerts`](/en/reference/rails/siloc/list-alerts) returns an active-only, keyset-paged feed. Alert types include `WINDOW_CLOSING` (a deposit/complement deadline approaches), `RECALCULATION` (a cycle is in a recálculo round), `RELAY_DOWN`, `CONNECTION_DOWN`, `CERTIFICATE_EXPIRY`, and `SCHEDULE_CHANGE` (an operator recorded a contingency schedule announcement). Alerts clear atomically when the underlying condition resolves. For example, a cycle that settles clears its `RECALCULATION` alert on the settle path. Pass `activeOnly=false` to include deactivated alerts as history.
* **Audit trail.** [`GET /api/v1/siloc/audit-records`](/en/reference/rails/siloc/list-audit-records) returns a paged, verbatim read of the audit trail, for example to export the record of an operator action or a participant status change. Bounds `from` and `to` are RFC3339 instants (date-only values are rejected).

## Schedule and contingency

***

The OT cycle grid and business-day calendar are compiled artifacts on the service. The API projects them verbatim and never parses a Núclea schedule wire.

* **Calendar and windows.** [`GET /api/v1/siloc/schedule/calendar`](/en/reference/rails/siloc/get-business-day-calendar) returns the business-day calendar, and [`GET /api/v1/siloc/schedule/windows`](/en/reference/rails/siloc/list-schedule-windows) returns the compiled canonical OT window grid. The grid is a static artifact, not a per-day read, and the service returns it even when the datastore is down.
* **Contingency schedule changes.** [`POST /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/record-schedule-change) records a contingency announcement the operator received out of band from Núclea. The body carries `reason` (≤500 chars), `origin` (the announcing channel or upstream reference, ≤256 chars), `effectiveAt`, the announced RFC 3339 instant the change takes effect, and an optional `windowSeq` naming the affected canonical window. The record is **append-only**: a later announcement never rewrites an earlier one. The newest announcement does become the single active `SCHEDULE_CHANGE` alert. Recording one clears the prior alert and raises a new one whose deadline is `effectiveAt` verbatim. [`GET /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/list-schedule-changes) returns the recorded changes, newest first.

Record a contingency schedule change:

```bash theme={null}
curl -X POST https://siloc.example.com/api/v1/siloc/schedule/changes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Núclea extended the OT window by 30 minutes",
    "origin": "Núclea e-mail ref 2026-07-22/01",
    "effectiveAt": "2026-07-22T18:30:00-03:00",
    "windowSeq": 2
  }'
```