rustkernel_clearing/
types.rs

1//! Clearing and settlement types.
2
3use std::collections::HashMap;
4
5// ============================================================================
6// Trade Types
7// ============================================================================
8
9/// A trade for clearing.
10#[derive(Debug, Clone)]
11pub struct Trade {
12    /// Trade ID.
13    pub id: u64,
14    /// Security/instrument ID.
15    pub security_id: String,
16    /// Buyer party ID.
17    pub buyer_id: String,
18    /// Seller party ID.
19    pub seller_id: String,
20    /// Trade quantity.
21    pub quantity: i64,
22    /// Trade price (in cents/smallest unit).
23    pub price: i64,
24    /// Trade date (Unix timestamp).
25    pub trade_date: u64,
26    /// Settlement date (Unix timestamp).
27    pub settlement_date: u64,
28    /// Trade status.
29    pub status: TradeStatus,
30    /// Trade type.
31    pub trade_type: TradeType,
32    /// Additional attributes.
33    pub attributes: HashMap<String, String>,
34}
35
36/// Trade status.
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
38pub enum TradeStatus {
39    /// Pending validation.
40    Pending,
41    /// Validated and ready for settlement.
42    Validated,
43    /// Matched for DVP.
44    Matched,
45    /// Netted into position.
46    Netted,
47    /// Settled successfully.
48    Settled,
49    /// Failed validation.
50    Failed,
51    /// Cancelled.
52    Cancelled,
53}
54
55/// Trade type.
56#[derive(Debug, Clone, Copy, PartialEq, Eq)]
57pub enum TradeType {
58    /// Regular trade.
59    Regular,
60    /// Repo/reverse repo.
61    Repo,
62    /// Securities lending.
63    SecLending,
64    /// Corporate action.
65    CorpAction,
66    /// Transfer.
67    Transfer,
68}
69
70impl Trade {
71    /// Create a new trade.
72    #[allow(clippy::too_many_arguments)]
73    pub fn new(
74        id: u64,
75        security_id: String,
76        buyer_id: String,
77        seller_id: String,
78        quantity: i64,
79        price: i64,
80        trade_date: u64,
81        settlement_date: u64,
82    ) -> Self {
83        Self {
84            id,
85            security_id,
86            buyer_id,
87            seller_id,
88            quantity,
89            price,
90            trade_date,
91            settlement_date,
92            status: TradeStatus::Pending,
93            trade_type: TradeType::Regular,
94            attributes: HashMap::new(),
95        }
96    }
97
98    /// Get total value (quantity * price).
99    pub fn value(&self) -> i64 {
100        self.quantity.saturating_mul(self.price)
101    }
102}
103
104// ============================================================================
105// Validation Types
106// ============================================================================
107
108/// Trade validation result.
109#[derive(Debug, Clone)]
110pub struct ValidationResult {
111    /// Trade ID.
112    pub trade_id: u64,
113    /// Is trade valid?
114    pub is_valid: bool,
115    /// Validation errors.
116    pub errors: Vec<ValidationError>,
117    /// Validation warnings.
118    pub warnings: Vec<String>,
119}
120
121/// Validation error.
122#[derive(Debug, Clone)]
123pub struct ValidationError {
124    /// Error code.
125    pub code: String,
126    /// Error message.
127    pub message: String,
128    /// Error severity.
129    pub severity: ErrorSeverity,
130}
131
132/// Error severity.
133#[derive(Debug, Clone, Copy, PartialEq, Eq)]
134pub enum ErrorSeverity {
135    /// Blocks settlement.
136    Critical,
137    /// May block settlement.
138    Warning,
139    /// Informational only.
140    Info,
141}
142
143/// Validation configuration.
144#[derive(Debug, Clone)]
145pub struct ValidationConfig {
146    /// Check counterparty eligibility.
147    pub check_counterparty: bool,
148    /// Check security eligibility.
149    pub check_security: bool,
150    /// Check position limits.
151    pub check_limits: bool,
152    /// Check settlement date validity.
153    pub check_settlement_date: bool,
154    /// Minimum settlement days from trade.
155    pub min_settlement_days: u32,
156    /// Maximum settlement days from trade.
157    pub max_settlement_days: u32,
158}
159
160impl Default for ValidationConfig {
161    fn default() -> Self {
162        Self {
163            check_counterparty: true,
164            check_security: true,
165            check_limits: true,
166            check_settlement_date: true,
167            min_settlement_days: 0,
168            max_settlement_days: 30,
169        }
170    }
171}
172
173// ============================================================================
174// DVP Types
175// ============================================================================
176
177/// DVP (Delivery vs Payment) instruction.
178#[derive(Debug, Clone)]
179pub struct DVPInstruction {
180    /// Instruction ID.
181    pub id: u64,
182    /// Trade ID.
183    pub trade_id: u64,
184    /// Security ID.
185    pub security_id: String,
186    /// Delivering party.
187    pub deliverer: String,
188    /// Receiving party.
189    pub receiver: String,
190    /// Quantity to deliver.
191    pub quantity: i64,
192    /// Payment amount.
193    pub payment_amount: i64,
194    /// Payment currency.
195    pub currency: String,
196    /// Settlement date.
197    pub settlement_date: u64,
198    /// Instruction status.
199    pub status: DVPStatus,
200}
201
202/// DVP status.
203#[derive(Debug, Clone, Copy, PartialEq, Eq)]
204pub enum DVPStatus {
205    /// Awaiting match.
206    Pending,
207    /// Matched with counterparty instruction.
208    Matched,
209    /// Securities delivered.
210    SecuritiesDelivered,
211    /// Payment made.
212    PaymentMade,
213    /// Fully settled.
214    Settled,
215    /// Failed.
216    Failed,
217}
218
219/// DVP matching result.
220#[derive(Debug, Clone)]
221pub struct DVPMatchResult {
222    /// Matched instruction pairs.
223    pub matched_pairs: Vec<(u64, u64)>,
224    /// Unmatched instructions.
225    pub unmatched: Vec<u64>,
226    /// Match rate.
227    pub match_rate: f64,
228    /// Matching details.
229    pub details: Vec<DVPMatchDetail>,
230}
231
232/// DVP match detail.
233#[derive(Debug, Clone)]
234pub struct DVPMatchDetail {
235    /// Delivery instruction ID.
236    pub delivery_id: u64,
237    /// Payment instruction ID.
238    pub payment_id: u64,
239    /// Match confidence.
240    pub confidence: f64,
241    /// Matching differences (if any).
242    pub differences: Vec<String>,
243}
244
245// ============================================================================
246// Netting Types
247// ============================================================================
248
249/// Netting position.
250#[derive(Debug, Clone)]
251pub struct NetPosition {
252    /// Party ID.
253    pub party_id: String,
254    /// Security ID.
255    pub security_id: String,
256    /// Net quantity (positive = receive, negative = deliver).
257    pub net_quantity: i64,
258    /// Net payment (positive = receive, negative = pay).
259    pub net_payment: i64,
260    /// Currency.
261    pub currency: String,
262    /// Contributing trades.
263    pub trade_ids: Vec<u64>,
264}
265
266/// Netting result.
267#[derive(Debug, Clone)]
268pub struct NettingResult {
269    /// Net positions per party/security.
270    pub positions: Vec<NetPosition>,
271    /// Gross trade count.
272    pub gross_trade_count: u64,
273    /// Net instruction count.
274    pub net_instruction_count: u64,
275    /// Netting efficiency (reduction ratio).
276    pub efficiency: f64,
277    /// Netting by party.
278    pub party_summary: HashMap<String, PartySummary>,
279}
280
281/// Party netting summary.
282#[derive(Debug, Clone, Default)]
283pub struct PartySummary {
284    /// Gross deliveries.
285    pub gross_deliveries: i64,
286    /// Gross receipts.
287    pub gross_receipts: i64,
288    /// Net position.
289    pub net_position: i64,
290    /// Gross payments.
291    pub gross_payments: i64,
292    /// Net payment.
293    pub net_payment: i64,
294    /// Trade count.
295    pub trade_count: u64,
296}
297
298/// Netting configuration.
299#[derive(Debug, Clone)]
300pub struct NettingConfig {
301    /// Net by security.
302    pub net_by_security: bool,
303    /// Net by settlement date.
304    pub net_by_settlement_date: bool,
305    /// Net by currency.
306    pub net_by_currency: bool,
307    /// Include failed trades.
308    pub include_failed: bool,
309}
310
311impl Default for NettingConfig {
312    fn default() -> Self {
313        Self {
314            net_by_security: true,
315            net_by_settlement_date: true,
316            net_by_currency: true,
317            include_failed: false,
318        }
319    }
320}
321
322// ============================================================================
323// Settlement Types
324// ============================================================================
325
326/// Settlement instruction.
327#[derive(Debug, Clone)]
328pub struct SettlementInstruction {
329    /// Instruction ID.
330    pub id: u64,
331    /// Party ID.
332    pub party_id: String,
333    /// Security ID.
334    pub security_id: String,
335    /// Instruction type.
336    pub instruction_type: InstructionType,
337    /// Quantity.
338    pub quantity: i64,
339    /// Payment amount.
340    pub payment_amount: i64,
341    /// Currency.
342    pub currency: String,
343    /// Settlement date.
344    pub settlement_date: u64,
345    /// Status.
346    pub status: SettlementStatus,
347    /// Source trade IDs.
348    pub source_trades: Vec<u64>,
349}
350
351/// Instruction type.
352#[derive(Debug, Clone, Copy, PartialEq, Eq)]
353pub enum InstructionType {
354    /// Deliver securities.
355    Deliver,
356    /// Receive securities.
357    Receive,
358    /// Make payment.
359    Pay,
360    /// Receive payment.
361    Collect,
362}
363
364/// Settlement status.
365#[derive(Debug, Clone, Copy, PartialEq, Eq)]
366pub enum SettlementStatus {
367    /// Pending execution.
368    Pending,
369    /// In progress.
370    InProgress,
371    /// Partially settled.
372    Partial,
373    /// Fully settled.
374    Settled,
375    /// Failed.
376    Failed,
377    /// On hold.
378    OnHold,
379}
380
381/// Settlement execution result.
382#[derive(Debug, Clone)]
383pub struct SettlementExecutionResult {
384    /// Successfully settled instructions.
385    pub settled: Vec<u64>,
386    /// Failed instructions.
387    pub failed: Vec<(u64, String)>,
388    /// Pending instructions.
389    pub pending: Vec<u64>,
390    /// Settlement rate.
391    pub settlement_rate: f64,
392    /// Total value settled.
393    pub value_settled: i64,
394    /// Total value failed.
395    pub value_failed: i64,
396}
397
398// ============================================================================
399// Efficiency Metrics
400// ============================================================================
401
402/// Zero balance frequency metrics.
403#[derive(Debug, Clone)]
404pub struct ZeroBalanceMetrics {
405    /// Party ID.
406    pub party_id: String,
407    /// Total settlement days analyzed.
408    pub total_days: u32,
409    /// Days with zero end-of-day balance.
410    pub zero_balance_days: u32,
411    /// Zero balance frequency (0-1).
412    pub frequency: f64,
413    /// Average end-of-day position.
414    pub avg_eod_position: f64,
415    /// Peak position.
416    pub peak_position: i64,
417    /// Intraday turnover.
418    pub avg_intraday_turnover: f64,
419}
420
421/// Settlement efficiency result.
422#[derive(Debug, Clone)]
423pub struct SettlementEfficiency {
424    /// Period analyzed (days).
425    pub period_days: u32,
426    /// Total instructions.
427    pub total_instructions: u64,
428    /// Settled on time.
429    pub on_time_settlements: u64,
430    /// Late settlements.
431    pub late_settlements: u64,
432    /// Failed settlements.
433    pub failed_settlements: u64,
434    /// On-time rate.
435    pub on_time_rate: f64,
436    /// Average settlement delay (seconds).
437    pub avg_delay_seconds: f64,
438    /// Zero balance metrics per party.
439    pub party_metrics: Vec<ZeroBalanceMetrics>,
440}
rustkernel_clearing/types.rs

rustkernel_clearing/
types.rs
