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

> Gateway connection lifecycle, MQ-configured SFN processing, supported-message dispatch, at-least-once delivery with durable deduplication, and certificate handling.

Lerian SILOC exposes a small set of typed operations over the `/api/v1/siloc` surface. The live surface covers connectivity and administration. A complete SILOC MQ connection descriptor activates inbound SFN processing, which dispatches supported message codes. The service also keeps the participant, certificate, and coverage records that support this work.

## Gateway connection lifecycle

***

When a complete SILOC MQ connection descriptor activates inbound SFN processing, the service opens and maintains **one** messaging-gateway connection to Nuclea's SILOC over the national financial-system network. Four guards protect the connection:

* a **circuit breaker** that trips on repeated failure,
* **automatic reconnect** with a capped backoff,
* a **credential-disabled stop** that halts the gateway after a certificate revocation, and
* a **readiness probe** that reports the gateway's connection and health.

Inbound SFN processing starts when you configure the complete SILOC MQ connection descriptor. If no connection trigger is present, 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. With the complete descriptor configured, the service decrypts and decodes inbound messages from the regulated envelope before it dispatches a supported message.

## Inbound SFN dispatch

***

After decoding, the ingress selects a route from a closed **(`CodProdt`, `CodMsg`)** policy. The same three funding codes have different destinations by product:

\| Code | OT | SLC |
\| --- | --- |
\| **PAG0102** | Durable period-opening deferral | Relay to Lerian SLC |
\| **LDL0021** | Durable deposit-instruction deferral | Relay to Lerian SLC |
\| **PAG0103** | Durable period-close deferral | Relay to Lerian SLC |
\| **PAG0101** | Durable participant-status deferral | Durable participant-status deferral |

The service does not support `LDL0020`, `LDL0006`, or any other product/code pair. They fail closed to an operator exception. The service never relays them as settlement funding. An undecodable envelope or a message with a blank `BCMSG.NUOp` follows the same fail-closed path.

## At-least-once dispatch with durable deduplication

***

The source can redeliver a message, so the SLC relay is **at-least-once**. For a successfully decoded SLC funding frame with a nonblank `BCMSG.NUOp`, the service checks durable deduplication by **`BCMSG.NUOp`** before relay. The policy treats that operation number as globally unique. The service does not use a message-ID-only key.

The service writes the processed-message record only after a successful relay and before it acknowledges the source. It creates no such record for an undecoded or unsupported message. A failure before that record is written can leave the message eligible for another delivery. Do not treat this behavior as an unconditional end-to-end exactly-once guarantee.

## Failure outcomes

***

* A **retryable** dispatch failure remains unacknowledged. With offset-safe source commits, the service reads the message again after a restart from the last committed offset. A persistent transient failure can stall its partition until restart.
* A **non-retryable** failure, such as a malformed envelope or an unsupported (`CodProdt`, `CodMsg`) pair, fails closed to a durable operator exception. The service acknowledges the message only after that exception record commits, so the partition can progress.
* The processed-message record protects only the successfully decoded and supported messages described above. It does not promise retention of every frame or exactly-once effects across every downstream system.

## Ingestion observability

***

* **List processed messages**: the audit feed of supported SFN messages that the service dispatched.
* **Read ingestion status**: the current health state of the enabled ingestion path, plus the last-dispatched 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 service holds the connection's regulated certificates as references, not as secrets. You **register** a public certificate together with an **external custody reference**. The service parses the certificate for its subject, serial, and validity window, and 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, it reports the direction, the implementation state, and the disposition.