> ## 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.

# How Lerian SILOC works

> The gateway connection lifecycle, inbound message demux, verbatim card-domain relay to Lerian SLC, exactly-once delivery, relay replay, the participant directory, regulated certificates, and capability coverage.

Lerian SILOC exposes its work as a small set of typed operations over the `/api/v1/siloc` surface. The live surface is connectivity and administration: one gateway connection to Nuclea, a verbatim relay of the card-domain settlement family to Lerian SLC, and the participant, certificate, and coverage records that support them.

## Gateway connection lifecycle

***

The service opens and maintains **one** messaging-gateway connection to Nuclea's SILOC over the national financial-system network. The connection is guarded by:

* a **circuit breaker** that trips on repeated failure,
* **automatic reconnect** with a capped backoff,
* a **credential-disabled stop** that halts the gateway when its certificate is disabled, and
* a **readiness probe** that reports whether the gateway is connected and healthy.

Every inbound message is decrypted and decoded from the regulated envelope before any processing begins.

## Inbound demux and verbatim card relay

***

Each decoded inbound message is classified by its message code. The **card funding and clearing family** is relayed **byte-for-byte** to Lerian SLC, the card-settlement service. The relay is inbound-only, and it forwards the decoded envelope verbatim — the service acts on none of the message's contents.

| Code        | Message             |
| ----------- | ------------------- |
| **LDL0021** | Deposit instruction |
| **LDL0020** | Credit settled      |
| **LDL0006** | Credit returned     |
| **PAG0102** | Cycle-period open   |
| **PAG0103** | Cycle-period close  |

Every other message — boleto, participant-status, other deferred families, and unknown codes — is recorded as a **fail-closed operator exception**. Such a message is never dropped and never mis-routed; it is held for an operator to review.

## Exactly-once relay

***

The gateway may redeliver a message at least once. Lerian SILOC de-duplicates on the **NUOp**, BACEN's globally unique per-operation identifier: the NUOp is consulted before a relay and recorded only after a durable relay. The downstream card-settlement service therefore receives each frame exactly once.

## Relay resilience and replay

***

* A **transient** relay error backs the frame out so the gateway redelivers it.
* A **sustained** relay outage parks the frame durably as a **relay failure** and raises a relay-down operational alert.
* An operator **lists** the parked relay failures and **replays** them once the downstream card-settlement service recovers.

No frame is lost and none is duplicated: at-least-once redelivery combined with NUOp deduplication guarantees both.

## Relay observability

***

* **List relayed messages** — the audit feed of the card-domain messages that have been relayed to Lerian SLC.
* **Read relay status** — the current health state of the relay, plus the last-relayed timestamp.

## Participant directory

***

Lerian SILOC keeps a directory of the SILOC participants it settles for. You **register**, **list**, **get**, and **update** a participant, and read a participant's **status**. Each participant carries its ISPB, its role, and its operational status.

Every registration seeds a status-history entry and emits a participant fact. Registration writes are idempotent through an idempotency key, so a retried registration does not create a duplicate.

| Role                     | Meaning                                                          |
| ------------------------ | ---------------------------------------------------------------- |
| **Direct**               | A direct SILOC participant.                                      |
| **Indirect**             | A participant that settles through another institution.          |
| **Settling institution** | The institution that settles on behalf of indirect participants. |

The operational status uses SILOC's seven-value status domain:

| Value | Status                             |
| ----- | ---------------------------------- |
| 1     | Participating                      |
| 2     | Excluded from the cycle            |
| 3     | Excluded from SILOC                |
| 6     | In cycle, excluded from SILOC      |
| 7     | Suspended                          |
| 8     | Suspended, excluded from the cycle |
| 9     | Inoperative (special regime)       |

## Regulated certificates

***

The connection's regulated certificates are held as references, not as secrets. You **register** a public certificate — parsed for its subject, serial, and validity window — together with an **external custody reference**; the service stores **no** private key. You then **list**, **get**, and **revoke** certificates over the same surface.

## Capability coverage

***

A read-only **capability listing** describes the settlement-coverage capabilities as a transparency surface: for each message type, its direction, whether it is implemented, and its disposition.