# NATS Events

Complete reference for NATS JetStream event subjects, payload formats, and integration patterns.

## Prerequisites

- NATS client library for your language
- NATS Server 2.10+ with JetStream enabled
- Network access to NATS cluster

## Event Architecture

```mermaid
graph TB
    subgraph Publishers
        SPI[SPI Service]
        DICT[Dict Service]
        SETTLE[Settlement Service]
    end

    subgraph NATS JetStream
        S1[MONETARIE_SPI<br/>monetarie.spi.>]
        S2[MONETARIE_DICT<br/>monetarie.dict.>]
        S3[MONETARIE_SETTLEMENT<br/>monetarie.settlement.>]
        S4[MONETARIE_CORE<br/>monetarie.core.>]
        S5[MONETARIE_AUDIT<br/>monetarie.audit.>]
        S6[MONETARIE_DLQ<br/>monetarie.dlq.>]
    end

    subgraph Consumers
        WORKERS[PIX Workers]
        CORE[Core Banking]
        CCS[CCS Service]
    end

    SPI --> S1
    DICT --> S2
    SETTLE --> S3
    S1 --> WORKERS
    S1 --> CORE
    S4 --> WORKERS
    S1 --> CCS
```

## SPI Events

| Subject | Description |
|---------|-------------|
| `monetarie.spi.transaction.created` | New transaction created |
| `monetarie.spi.transaction.processing` | Transaction in processing (ACSP) |
| `monetarie.spi.transaction.settled` | Transaction settled (STLD) |
| `monetarie.spi.transaction.rejected` | Transaction rejected (RJCT) |
| `monetarie.spi.transaction.returned` | Transaction returned (RTRN) |
| `monetarie.spi.transaction.cancelled` | Transaction cancelled (CANC) |
| `monetarie.spi.inbound.received` | Inbound payment received from BACEN |
| `monetarie.spi.outbound.sent` | Outbound payment sent to BACEN |
| `monetarie.spi.balance.updated` | Balance changed |

### SPI Event Payload

```json
{
  "type": "transaction.settled",
  "source": "pix",
  "published_at": "2026-02-09T14:30:00Z",
  "data": {
    "transaction_id": "uuid",
    "end_to_end_id": "E12345678202602091430abcdef123456",
    "message_type": "pacs.008",
    "amount": 10000,
    "status": "STLD",
    "direction": "OUTBOUND",
    "debtor_ispb": "12345678",
    "creditor_ispb": "87654321",
    "operation_time": "2026-02-09T14:30:00.000Z",
    "settlement_time": "2026-02-09T14:30:01.200Z"
  }
}
```

## DICT Events

| Subject | Description |
|---------|-------------|
| `monetarie.dict.keys.created` | PIX key registered |
| `monetarie.dict.keys.deleted` | PIX key deleted |
| `monetarie.dict.keys.claimed` | Ownership claim initiated |
| `monetarie.dict.keys.ported` | Key portability completed |
| `monetarie.dict.cid.synced` | CID synchronization event |

## Core Banking Events

### Core -> PIX

| Subject | Description |
|---------|-------------|
| `monetarie.core.pix.payment_request` | Create outbound payment |
| `monetarie.core.pix.return_request` | Create return (pacs.004) |
| `monetarie.core.pix.key_create` | Register PIX key |
| `monetarie.core.pix.key_delete` | Delete PIX key |
| `monetarie.core.pix.dict_lookup` | DICT key lookup |
| `monetarie.core.pix.balance_inquiry` | Balance query |

### Core -> PIX Payload Example

```json
{
  "event": "payment_request",
  "correlation_id": "uuid",
  "data": {
    "amount": 10000,
    "creditor_key": "email@example.com",
    "debtor_account": "12345",
    "debtor_ispb": "12345678",
    "description": "Payment for services"
  }
}
```

::: warning ROUTING KEY
The `"event"` field is the routing key for CoreEventProcessor. If missing or misspelled, the message is silently acknowledged without processing.
:::

## Request/Reply (Non-JetStream)

| Subject | Direction | Purpose |
|---------|-----------|---------|
| `dict.lookup.request` | Core <-> PIX | DICT key lookup |
| `dict.api.request` | Core <-> PIX | Claims/MED/infractions |

These subjects are outside JetStream scope to avoid stream interception.

## Consuming Events

### NATS Client Example (Go)

```go
js, _ := nc.JetStream()

sub, _ := js.Subscribe("monetarie.spi.transaction.>", func(msg *nats.Msg) {
    var event map[string]interface{}
    json.Unmarshal(msg.Data, &event)

    // Process event
    fmt.Printf("Event: %s\n", event["type"])

    // Acknowledge
    msg.Ack()
}, nats.Durable("my-consumer"))
```

### NATS Client Example (Node.js)

```javascript
const { connect, JSONCodec } = require("nats")

const nc = await connect({ servers: "10.10.40.5:4222" })
const js = nc.jetstream()
const jc = JSONCodec()

const sub = await js.subscribe("monetarie.spi.transaction.>", {
  durable: "my-consumer"
})

for await (const msg of sub) {
  const event = jc.decode(msg.data)
  console.log(`Event: ${event.type}`)
  msg.ack()
}
```

## Message Headers

All NATS messages include:

| Header | Description |
|--------|-------------|
| `trace_id` | Distributed trace ID for log correlation |
| `Nats-Msg-Id` | Deduplication ID |
| `published_at` | ISO 8601 timestamp |

## Expected Outcome

After integrating with NATS events:

- Real-time event consumption from PIX streams
- Core Banking events flowing bidirectionally
- Distributed tracing via `trace_id` header
- At-least-once delivery with durable consumers