> ## 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, opt-in SFN ingestion, 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. SFN ingestion is opt-in; when enabled, the service dispatches its supported message codes. It also keeps the participant, certificate, and coverage records that support this work.

## Gateway connection lifecycle

***

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.

`SFN_INGEST_ENABLED` defaults to `false`. Set it to `true` to enable the consumer; when enabled, the service decrypts and decodes inbound messages from the regulated envelope before it dispatches a supported message.

## Inbound SFN dispatch

***

After decoding, the ingress dispatches a supported message by its `CodMsg`. It accepts the following codes:

| Code                    | Dispatch            |
| ----------------------- | ------------------- |
| **PAG0102**             | Period opening      |
| **LDL0021**             | Deposit instruction |
| **LDL0020 / LDL0020R2** | Credit settled      |
| **LDL0006 / LDL0006R2** | Credit returned     |
| **PAG0103**             | Period close        |

The ingress does **not** route `PAG0101`. An unsupported code, an undecodable envelope, or a message with a blank `BCMSG.NUOp` is non-retryable: it bypasses dispatch, follows the dead-letter path, and is acknowledged. These messages have no processed-message deduplication key.

## At-least-once dispatch with durable deduplication

***

The source can redeliver a message, so dispatch is **at-least-once**. For a successfully decoded, supported message with a nonblank `BCMSG.NUOp`, the service checks durable deduplication by the composite key **(`BCMSG.NUOp`, `CodMsg`)** before dispatch. It does not deduplicate by a message ID alone.

The service writes the processed-message record only after a successful dispatch 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 message is read 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 code, follows the dead-letter path and is acknowledged 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.