/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:
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.
The operational status uses SILOC’s seven-value status domain:
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.