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	email, id, role_id
RoleCreated	A new role was created	id, name

---

Accounting Events

Events related to chart of accounts and accounting operations. Ledger account, membership, transaction, entry, and effective-balance payloads use GL-qualified field names (such as gl_account_id and gl_transaction_effective_date), independent of the underlying ledger engine. Transaction-template payloads retain their template field names.

Event	Description	Payload Fields
ChartNodeCreated	A chart of accounts node was created	account_set_id, chart_id, code, id, name, normal_balance_type, parent
LedgerAccountCreated	A general-ledger account was created	gl_account_code, gl_account_entity_id, gl_account_entity_type, gl_account_external_id, gl_account_id, gl_account_name, gl_account_normal_balance_type
LedgerAccountSetMemberCreated	An account or nested account set was added to a general-ledger account set	gl_account_set_id, gl_member_id, gl_member_type
LedgerAccountSetMemberRemoved	An account or nested account set was removed from a general-ledger account set	gl_account_set_id, gl_member_id, gl_member_type
LedgerTransactionCreated	A general-ledger transaction was posted, including its effective date and closing-transaction flag	gl_journal_id, gl_transaction_created_at, gl_transaction_effective_date, gl_transaction_id, gl_transaction_modified_at, gl_transaction_template_id, is_closing_gl_transaction
LedgerEntryCreated	A general-ledger entry was posted with its direction, layer, currency, and native amount	gl_account_id, gl_entry_amount_native, gl_entry_currency, gl_entry_direction, gl_entry_id, gl_entry_layer, gl_entry_type, gl_journal_id, gl_transaction_id
LedgerTxTemplateCreated	A transaction template was created with its entry definitions	code, description, entries, id, version
LedgerEffectiveBalance	An effective-date general-ledger balance was captured during end-of-day processing	gl_account_id, gl_balance_currency, gl_balance_effective_date, gl_balance_encumbrance_cr, gl_balance_encumbrance_dr, gl_balance_pending_cr, gl_balance_pending_dr, gl_balance_settled_cr, gl_balance_settled_dr, gl_journal_id

---

Credit Events

Events related to credit facility lifecycle and operations.

Event	Description	Payload Fields
FacilityProposalCreated	A credit facility proposal was created	amount, created_at, customer_id, id, partner_id, product_id, status, terms
FacilityProposalConcluded	A credit facility proposal was concluded	amount, created_at, customer_id, id, partner_id, product_id, status, terms
PendingCreditFacilityCollateralizationChanged	Collateralization state changed for pending facility	amount, collateralization, completed_at, created_at, credit_facility_proposal_id, customer_id, id, partner_id, product_id, status, terms
PendingCreditFacilityCompleted	A pending credit facility was completed	amount, collateralization, completed_at, created_at, credit_facility_proposal_id, customer_id, id, partner_id, product_id, status, terms
FacilityActivated	A credit facility was activated	account_ids, accrual_spec, activated_at, activated_on, activation_tx_id, amount, collateral_id, collateralization, completed_at, customer_id, id, liquidation_trigger, maturity_date, partner_id, pending_credit_facility_id, product_id, public_id, terms
FacilityCompleted	A credit facility was fully repaid and closed	account_ids, accrual_spec, activated_at, activated_on, activation_tx_id, amount, collateral_id, collateralization, completed_at, customer_id, id, liquidation_trigger, maturity_date, partner_id, pending_credit_facility_id, product_id, public_id, terms
FacilityCollateralizationChanged	Collateralization state changed for active facility	account_ids, accrual_spec, activated_at, activated_on, activation_tx_id, amount, collateral_id, collateralization, completed_at, customer_id, id, liquidation_trigger, maturity_date, partner_id, pending_credit_facility_id, product_id, public_id, terms
DisbursalInitialized	A disbursal was initiated and is pending approval	amount, approved, cancelled, credit_facility_id, customer_id, due_date, id, obligation_id, partner_id, public_id, settlement, status
DisbursalApprovalConcluded	A disbursal approval process was concluded	amount, approved, cancelled, credit_facility_id, customer_id, due_date, id, obligation_id, partner_id, public_id, settlement, status
DisbursalSettled	A disbursal was settled	amount, approved, cancelled, credit_facility_id, customer_id, due_date, id, obligation_id, partner_id, public_id, settlement, status
DisbursalCancelled	A disbursal was cancelled	amount, approved, cancelled, credit_facility_id, customer_id, due_date, id, obligation_id, partner_id, public_id, settlement, status
AccrualPosted	Interest accrual was posted	credit_facility_id, due_at, id, period, posting
FacilityMatured	No description available	account_ids, accrual_spec, activated_at, activated_on, activation_tx_id, amount, collateral_id, collateralization, completed_at, customer_id, id, liquidation_trigger, maturity_date, partner_id, pending_credit_facility_id, product_id, public_id, terms
PartialLiquidationInitiated	A partial liquidation was initiated	facility_accounts, facility_accrual_spec, facility_activated_at, facility_activated_on, facility_activation_tx_id, facility_amount, facility_collateral_id, facility_collateralization, facility_completed_at, facility_customer_id, facility_id, facility_liquidation_trigger, facility_maturity_date, facility_partner_id, facility_pending_credit_facility_id, facility_product_id, facility_public_id, facility_terms, id, initially_estimated_to_liquidate, initially_expected_to_receive, trigger_exchange_rate

---

CreditCollateral Events

Events related to credit facility collateral management and liquidation.

Event	Description	Payload Fields
CollateralUpdated	Collateral amount was updated	amount, id, last_posting, secured_loan_id
LiquidationCollateralSentOut	Collateral was sent for liquidation	amount, effective, ledger_tx_id, liquidation_id, secured_loan_id
LiquidationSaleRecorded	An executed collateral sale was recorded and its net proceeds recognized as a receivable	collateral_id, effective, ledger_tx_id, liquidation_id, net_proceeds, payment_id, secured_loan_id

---

CreditCollection Events

Events related to credit facility obligations and payment collection.

Event	Description	Payload Fields
PaymentCreated	A payment was created	amount, beneficiary_id, created_at, effective, id
PaymentAllocationCreated	A payment allocation was created	amount, beneficiary_id, created_at, effective, id, obligation_id, obligation_type, payment_id
ObligationCreated	A new obligation was created	beneficiary_id, beneficiary_owner_id, completed_at, completing_payment_allocation_id, created_at, defaulted_at, due_at, effective, id, initial_amount, obligation_type, outstanding_amount, overdue_at
ObligationDue	An obligation became due	beneficiary_id, beneficiary_owner_id, completed_at, completing_payment_allocation_id, created_at, defaulted_at, due_at, effective, id, initial_amount, obligation_type, outstanding_amount, overdue_at
ObligationOverdue	An obligation became overdue	beneficiary_id, beneficiary_owner_id, completed_at, completing_payment_allocation_id, created_at, defaulted_at, due_at, effective, id, initial_amount, obligation_type, outstanding_amount, overdue_at
ObligationDefaulted	An obligation defaulted	beneficiary_id, beneficiary_owner_id, completed_at, completing_payment_allocation_id, created_at, defaulted_at, due_at, effective, id, initial_amount, obligation_type, outstanding_amount, overdue_at
ObligationCompleted	An obligation was fully paid	beneficiary_id, beneficiary_owner_id, completed_at, completing_payment_allocation_id, created_at, defaulted_at, due_at, effective, id, initial_amount, obligation_type, outstanding_amount, overdue_at

---

Custody Events

Events related to Bitcoin custody and wallet management.

Event	Description	Payload Fields
WalletBalanceUpdated	No description available	address, balance, id, network

---

Customer Events

Events related to customer lifecycle and KYC.

Event	Description	Payload Fields
CustomerCreated	A new customer was created	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerFrozen	A customer account was frozen, blocking financial operations	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerUnfrozen	A previously frozen customer account was unfrozen, restoring normal operations	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerClosed	Customer account was closed	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerPiiErasureScheduled	PII erasure was scheduled for a closed customer's party	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerPiiErasureCancelled	A scheduled PII erasure for a customer's party was cancelled before execution	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerPiiErasureCompleted	A scheduled PII erasure for a customer's party was carried out	customer_type, id, partner_id, party_ref_id, party_ref_type, public_id, status_change
CustomerDocumentCreated	A document was added to a customer	customer_id, id
CustomerDocumentArchived	A customer document was archived	customer_id, id
CustomerDocumentDeletionRequested	A customer document's deletion was requested	customer_id, id
CustomerNoteCreated	A note was added to a customer	customer_id, id
ProspectCreated	A new prospect was created for onboarding	customer_type, id, partner_id, party_ref_id, party_ref_type, stage
ProspectConverted	A prospect was converted to a customer	customer_type, id, partner_id, party_ref_id, party_ref_type, stage
ProspectClosed	A prospect was closed without converting	customer_type, id, partner_id, party_ref_id, party_ref_type, stage
ProspectPiiErasureScheduled	PII erasure was scheduled for a closed prospect's party	customer_type, id, partner_id, party_ref_id, party_ref_type, stage
ProspectPiiErasureCancelled	A scheduled PII erasure for a prospect's party was cancelled before execution	customer_type, id, partner_id, party_ref_id, party_ref_type, stage

---

Deposit Events

Events related to deposit accounts and transactions.

Event	Description	Payload Fields
DepositAccountProductCreated	A deposit account product was created for one customer type with its currency and accounting topology	accounting_integration, currency, customer_type, id, name, partner_id
DepositAccountCreated	A deposit account was created	account_holder_id, activity, currency, id, product_id, public_id, status
DepositAccountFrozen	No description available	account_holder_id, activity, currency, id, product_id, public_id, status
DepositAccountUnfrozen	No description available	account_holder_id, activity, currency, id, product_id, public_id, status
DepositAccountClosed	No description available	account_holder_id, activity, currency, id, product_id, public_id, status
DepositAccountActivityUpdated	No description available	account_holder_id, activity, currency, id, product_id, public_id, status
DepositBooked	A deposit was booked	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, public_id, reference, status
DepositReverted	A deposit was reverted	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, public_id, reference, status
WithdrawalInitialized	A withdrawal was initiated and is pending approval	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status
WithdrawalApprovalConcluded	A withdrawal approval process was concluded	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status
WithdrawalDenied	A withdrawal was denied	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status
WithdrawalConfirmed	A withdrawal was confirmed	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status
WithdrawalCancelled	A withdrawal was cancelled	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status
WithdrawalReverted	A confirmed withdrawal was reverted	account_holder_id, amount, deposit_account_id, id, ledger_tx_id, payout_id, public_id, reference, status

---

Exchange Events

Events related to bitcoin purchases executed for customers.

Event	Description	Payload Fields
BitcoinPurchaseExecuted	A customer's fiat was exchanged for bitcoin and both deposit accounts were settled	bitcoin_amount, customer_id, destination_deposit_account_id, fiat_amount, id, ledger_tx_id, public_id, source_deposit_account_id

---

Partner Events

Events related to partner and partner user lifecycle.

Event	Description	Payload Fields
PartnerUserCreated	A partner user was created	email, id, partner_id
PartnerCreated	A partner was created	id, name, status
PartnerRenamed	A partner was renamed	id, name, status
PartnerActivated	A partner was activated	id, name, status
PartnerClosed	A partner was closed	id, name, status

---

Price Events

Official rate events published at end of day and on the hour tick; runtime price updates are ephemeral and never persisted.

Event	Description	Payload Fields
ClosingRateCaptured	Official closing rate for one currency pair on one business day, published by the capture-closing-rates EOD phase. Runtime prices are ephemeral.	closing_time, day, pair, provenance, rate_major, window
RateSnapshotCaptured	The runtime's latest sanitized rate for one currency pair, republished as a persistent event on each hour tick. No provider fetch happens at the tick: the rate, sanitization window, and provenance come from the record the realtime aggregation pipeline already produced, so hourly-refreshed reports convert at exactly the rate the bank was using.	hour, pair, provenance, rate_major, window

---

DwPipeline Events

Telemetry for the data-warehouse refresh pipeline runs: EOD builds, intraday refreshes, and on-demand full or partial dbt refreshes. Report serving publishes no events.

Event	Description	Payload Fields
PipelineRunInitialized	A scheduled or on-demand pipeline run was queued to refresh the data warehouse	day, id, kind, status
PipelineRunStarted	The pipeline run started dbt against the data warehouse	day, id, kind, status
PipelineRunCompleted	The pipeline run finished refreshing the data warehouse for the day	day, id, kind, status
PipelineRunFailed	The pipeline run failed; the failure reason is recorded on the entity	day, id, kind, status
PipelineRunSkipped	The pending scheduled run was superseded during queue compaction without running dbt or advancing report freshness	day, id, kind, status

---

Governance Events

Events related to approval workflows.

Event	Description	Payload Fields
ApprovalProcessConcluded	An approval process was concluded	id, process_type, status, target_ref

---

Time Events

Events related to end-of-day processing.

Event	Description	Payload Fields
EndOfDay	The operational clock rolled past the closing time for the configured timezone; the raw day-boundary signal that day-scoped reactions and the EOD close process key off	closed_at, day, schedule
HourTick	The operational clock crossed into a new hour; the hourly intraday signal that periodic (non-EOD) reactions key off. Published at most once per hour boundary, with missed boundaries coalesced into one tick	hour

---

Lifecycle Events

Durable core banking lifecycle milestones, published once per database rather than on each process restart.

Event	Description	Payload Fields
InitializationCompleted	All synchronous core banking startup initialization completed successfully. Triggers the initial full warehouse build; consumers may subscribe to perform other one-time setup. The marker and event are committed atomically, including across concurrent replicas	completedAt

---

Eod Events

Events related to the end-of-day close process.

Event	Description	Payload Fields
EodProcessInitialized	An end-of-day close process was created for a business day	day, id, status, timezone
EodProcessInProgress	An end-of-day close process advanced: a phase started, completed, or failed	day, id, status, timezone
EodProcessCompleted	An end-of-day close process finished with every phase successful: the day's ledger mutations are all posted and its balances snapshotted, so the day is settled history	day, id, status, timezone
EodProcessStopped	An end-of-day close process stopped, either after a blocking phase failure or once no phases remain to run	day, id, status, timezone

---

DomainConfig Events

Events related to runtime domain configuration. Only configs defined as published are reported.

Event	Description	Payload Fields
Updated	A published domain config was written, carrying its committed value rendered as text with its config type	config_type, id, key, value

---

Event Types Reference

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

Module	Event Type Prefix
Access	core.access.*
Accounting	core.accounting.*
Credit	core.credit.*
CreditCollateral	core.credit-collateral.*
CreditCollection	core.credit-collection.*
Custody	core.custody.*
Customer	core.customer.*
Deposit	core.deposit.*
Exchange	core.exchange.*
Partner	core.partner.*
Price	core.price.*
DwPipeline	core.dw-pipeline.*
Governance	governance.*
Time	core.time.*
Lifecycle	core.lifecycle.*
Eod	core.eod.*
DomainConfig	core.domain-config.*

---

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. Reporting warehouse - Via the outbox relay into Postgres DW

For integration details, contact the platform team.