Domain Events

Lana Bank publishes domain events via the transactional outbox pattern. These events can be consumed by external systems for integration, analytics, and audit purposes.

All events are serialized as JSON and include metadata for tracing and ordering.

---

Event Structure

Each event is wrapped in an envelope with the following structure:

{
  "id": "uuid",
  "event_type": "core.credit.facility-activated",
  "payload": { ... },
  "recorded_at": "2024-01-15T10:30:00Z",
  "trace_id": "trace-uuid"
}

---

Access Events

Events related to user and role management.

Event	Description	Payload Fields
UserCreated	A new user was created	entity
RoleCreated	A new role was created	entity

---

Credit Events

Events related to credit facility lifecycle and operations.

Event	Description	Payload Fields
FacilityProposalCreated	A credit facility proposal was created	entity
FacilityProposalConcluded	A credit facility proposal was concluded	entity
PendingCreditFacilityCollateralizationChanged	Collateralization state changed for pending facility	entity
PendingCreditFacilityCompleted	A pending credit facility was completed	entity
FacilityActivated	A credit facility was activated	entity
FacilityCompleted	A credit facility was fully repaid and closed	entity
FacilityCollateralizationChanged	Collateralization state changed for active facility	entity
DisbursalInitialized	A disbursal was initiated and is pending approval	entity
DisbursalApprovalConcluded	A disbursal approval process was concluded	entity
DisbursalSettled	A disbursal was settled	entity
DisbursalCancelled	A disbursal was cancelled	entity
AccrualPosted	Interest accrual was posted	entity
FacilityMatured	No description available	entity
PartialLiquidationInitiated	A partial liquidation was initiated	entity

---

CreditCollateral Events

Events related to credit facility collateral management and liquidation.

Event	Description	Payload Fields
CollateralUpdated	Collateral amount was updated	entity
LiquidationCollateralSentOut	Collateral was sent for liquidation	amount, effective, ledger_tx_id, liquidation_id, recorded_at, secured_loan_id
LiquidationProceedsReceived	Liquidation proceeds were received	amount, collateral_id, effective, ledger_tx_id, liquidation_id, payment_id, recorded_at, secured_loan_id
LiquidationCompleted	Liquidation was completed	liquidation_id, secured_loan_id

---

CreditCollection Events

Events related to credit facility obligations and payment collection.

Event	Description	Payload Fields
PaymentCreated	A payment was created	entity
PaymentAllocationCreated	A payment allocation was created	entity
ObligationCreated	A new obligation was created	entity
ObligationDue	An obligation became due	entity
ObligationOverdue	An obligation became overdue	entity
ObligationDefaulted	An obligation defaulted	entity
ObligationCompleted	An obligation was fully paid	entity

---

Custody Events

Events related to Bitcoin custody and wallet management.

Event	Description	Payload Fields
WalletBalanceUpdated	No description available	entity

---

Customer Events

Events related to customer lifecycle and KYC.

Event	Description	Payload Fields
CustomerCreated	A new customer was created	entity
CustomerFrozen	A customer account was frozen, blocking financial operations	entity
CustomerUnfrozen	A previously frozen customer account was unfrozen, restoring normal operations	entity
CustomerClosed	Customer account was closed	entity
PartyCreated	No description available	entity
PartyEmailUpdated	No description available	entity
ProspectCreated	A new prospect was created for onboarding	entity
ProspectKycStarted	A prospect started KYC verification	entity
ProspectKycPending	A prospect's KYC verification is pending review	entity
ProspectKycDeclined	A prospect's KYC verification was declined	entity
ProspectConverted	A prospect was converted to a customer	entity
ProspectClosed	A prospect was closed without converting	entity

---

Deposit Events

Events related to deposit accounts and transactions.

Event	Description	Payload Fields
DepositAccountCreated	A deposit account was created	entity
DepositInitialized	A deposit was initialized	entity
DepositReverted	A deposit was reverted	entity
WithdrawalInitialized	A withdrawal was initiated and is pending approval	entity
WithdrawalApprovalConcluded	A withdrawal approval process was concluded	entity
WithdrawalDenied	A withdrawal was denied	entity
WithdrawalConfirmed	A withdrawal was confirmed	entity
WithdrawalCancelled	A withdrawal was cancelled	entity
WithdrawalReverted	A confirmed withdrawal was reverted	entity

---

Price Events

Events related to BTC/USD price updates.

Event	Description	Payload Fields
PriceUpdated	BTC/USD price was updated	price, timestamp
ProviderPriceFetched	No description available	price, provider_id, timestamp

---

Report Events

Events related to report generation.

Event	Description	Payload Fields
ReportRunCreated	A report run was initiated	entity
ReportRunStateUpdated	A report run state changed	entity

---

Governance Events

Events related to approval workflows.

Event	Description	Payload Fields
ApprovalProcessConcluded	An approval process was concluded	entity

---

Time Events

Events related to end-of-day processing.

Event	Description	Payload Fields
EndOfDay	End of day was reached for the configured timezone	closing_time, day, timezone

---

Event Types Reference

All event types follow the naming convention: core.<module>.<event-name>

Module	Event Type Prefix
Access	core.access.*
Credit	core.credit.*
CreditCollateral	core.credit-collateral.*
CreditCollection	core.credit-collection.*
Custody	core.custody.*
Customer	core.customer.*
Deposit	core.deposit.*
Price	core.price.*
Report	core.report.*
Governance	governance.*
Time	core.time.*

---

Consuming Events

Events are published via the transactional outbox and can be consumed through:

1. Direct database polling - Query the outbox table
2. Event streaming - Integration with message queues (implementation dependent)
3. ETL pipelines - Via Meltano extraction

For integration details, contact the platform team.