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

# Como o Lerian SILOC funciona

> O ciclo de vida da conexão do gateway, o demux de mensagens recebidas, o relay literal do domínio de cartões para o Lerian SLC, a entrega exatamente-uma-vez, o replay do relay, o diretório de participantes, os certificados regulados e a cobertura de capacidades.

O Lerian SILOC expõe o seu trabalho como um conjunto reduzido de operações tipadas sobre a superfície `/api/v1/siloc`. A superfície viva é conectividade e administração: uma conexão de gateway à Nuclea, um relay literal da família de liquidação do domínio de cartões para o Lerian SLC, e os registros de participantes, certificados e cobertura que os sustentam.

## Ciclo de vida da conexão do gateway

***

O serviço abre e mantém **uma** conexão de gateway de mensageria ao SILOC da Nuclea sobre a rede nacional do sistema financeiro. A conexão é protegida por:

* um **circuit breaker** que dispara diante de falhas repetidas,
* **reconexão automática** com um backoff limitado,
* uma **parada por credencial desabilitada** que interrompe o gateway quando o seu certificado está desabilitado, e
* uma **sonda de readiness** que reporta se o gateway está conectado e saudável.

Cada mensagem recebida é descriptografada e decodificada a partir do envelope regulado antes de qualquer processamento começar.

## Demux de entrada e relay literal de cartões

***

Cada mensagem recebida decodificada é classificada pelo seu código de mensagem. A **família de fundeamento e clearing de cartões** é retransmitida **byte a byte** para o Lerian SLC, o serviço de liquidação de cartões. O relay é apenas de entrada e repassa o envelope decodificado de forma literal — o serviço não age sobre nenhum dos conteúdos da mensagem.

| Código      | Mensagem                       |
| ----------- | ------------------------------ |
| **LDL0021** | Instrução de depósito          |
| **LDL0020** | Crédito liquidado              |
| **LDL0006** | Crédito devolvido              |
| **PAG0102** | Abertura de período de ciclo   |
| **PAG0103** | Fechamento de período de ciclo |

Qualquer outra mensagem — boleto, status de participante, outras famílias diferidas e códigos desconhecidos — é registrada como uma **exceção de operador fail-closed**. Essa mensagem nunca é descartada nem roteada incorretamente; ela é retida para um operador revisar.

## Relay exatamente-uma-vez

***

O gateway pode reentregar uma mensagem ao menos uma vez. O Lerian SILOC deduplica pelo **NUOp**, o identificador único por operação do BACEN: o NUOp é consultado antes de um relay e registrado apenas após um relay durável. O serviço de liquidação de cartões recebe assim cada frame exatamente uma vez.

## Resiliência e replay do relay

***

* Um erro de relay **transitório** devolve o frame para o gateway reentregá-lo.
* Uma interrupção de relay **sustentada** estaciona o frame de forma durável como uma **falha de relay** e levanta um alerta operacional de relay caído.
* Um operador **lista** as falhas de relay estacionadas e as **reprocessa** assim que o serviço de liquidação de cartões se recupera.

Nenhum frame se perde e nenhum é duplicado: a reentrega ao-menos-uma-vez combinada com a deduplicação pelo NUOp garante ambas as coisas.

## Observabilidade do relay

***

* **Listar mensagens retransmitidas** — o feed de auditoria das mensagens do domínio de cartões que foram retransmitidas para o Lerian SLC.
* **Ler o status do relay** — o estado de saúde atual do relay, mais a marca de tempo do último relay.

## Diretório de participantes

***

O Lerian SILOC mantém um diretório dos participantes do SILOC pelos quais liquida. Você **registra**, **lista**, **obtém** e **atualiza** um participante, e lê o **status** de um participante. Cada participante carrega o seu ISPB, o seu papel e o seu status operacional.

Cada registro semeia uma entrada de histórico de status e emite um fato de participante. As escritas de registro são idempotentes por meio de uma chave de idempotência, de modo que um registro repetido não cria um duplicado.

| Papel                      | Significado                                                    |
| -------------------------- | -------------------------------------------------------------- |
| **Direto**                 | Um participante direto do SILOC.                               |
| **Indireto**               | Um participante que liquida através de outra instituição.      |
| **Instituição liquidante** | A instituição que liquida em nome dos participantes indiretos. |

O status operacional usa o domínio de status de sete valores do SILOC:

| Valor | Status                       |
| ----- | ---------------------------- |
| 1     | Participando                 |
| 2     | Excluído do ciclo            |
| 3     | Excluído do SILOC            |
| 6     | Em ciclo, excluído do SILOC  |
| 7     | Suspenso                     |
| 8     | Suspenso, excluído do ciclo  |
| 9     | Inoperante (regime especial) |

## Certificados regulados

***

Os certificados regulados da conexão são conservados como referências, não como segredos. Você **registra** um certificado público — analisado pelo seu titular, número de série e janela de validade — junto com uma **referência de custódia externa**; o serviço não armazena **nenhuma** chave privada. Você então **lista**, **obtém** e **revoga** certificados sobre a mesma superfície.

## Cobertura de capacidades

***

Uma **listagem de capacidades** somente leitura descreve as capacidades de cobertura de liquidação como uma superfície de transparência: para cada tipo de mensagem, a sua direção, se está implementado e a sua disposição.