templar_vault_kernel/
lib.rs

1#![no_std]
2
3extern crate alloc;
4#[cfg(any(test, feature = "std", feature = "schemars", feature = "borsh-schema"))]
5extern crate std;
6
7pub mod abort;
8pub mod actions;
9pub mod address_book;
10pub mod effects;
11pub mod error;
12pub mod fee;
13pub mod math;
14pub mod restrictions;
15pub mod state;
16
17#[doc(hidden)]
18pub mod test_utils;
19pub mod transitions;
20pub mod types;
21pub mod utils;
22
23/// Whether the `action-recovery` feature is enabled in this resolved kernel build.
24pub const ACTION_RECOVERY_ENABLED: bool = cfg!(feature = "action-recovery");
25/// Whether the `action-sync-external` feature is enabled in this resolved kernel build.
26pub const ACTION_SYNC_EXTERNAL_ENABLED: bool = cfg!(feature = "action-sync-external");
27/// Whether the `action-refresh-fees` feature is enabled in this resolved kernel build.
28pub const ACTION_REFRESH_FEES_ENABLED: bool = cfg!(feature = "action-refresh-fees");
29/// Whether the `action-allocation-lifecycle` feature is enabled in this resolved kernel build.
30pub const ACTION_ALLOCATION_LIFECYCLE_ENABLED: bool = cfg!(feature = "action-allocation-lifecycle");
31/// Whether the `action-refresh-lifecycle` feature is enabled in this resolved kernel build.
32pub const ACTION_REFRESH_LIFECYCLE_ENABLED: bool = cfg!(feature = "action-refresh-lifecycle");
33/// Whether the `action-pause` feature is enabled in this resolved kernel build.
34pub const ACTION_PAUSE_ENABLED: bool = cfg!(feature = "action-pause");
35
36pub use actions::{
37    apply_action, compute_fee_accrual, convert_to_assets, convert_to_assets_bounded,
38    convert_to_assets_ceil, convert_to_assets_ceil_bounded, convert_to_redeem_assets,
39    convert_to_redeem_assets_bounded, convert_to_shares, convert_to_shares_bounded,
40    convert_to_shares_ceil, convert_to_shares_ceil_bounded,
41    convert_to_withdraw_shares_ceil_bounded, convert_to_withdrawable_shares, effective_totals,
42    plan_idle_payout, preview_deposit_shares, preview_withdraw_assets,
43    should_refresh_fees_for_value_transfer, EffectiveTotals, FeeAccrualOutcome, FeeAccrualOverflow,
44    IdlePayoutPlan, KernelAction, KernelResult, PayoutOutcome,
45};
46pub use address_book::AddressBook;
47pub use fee::{Fee, FeeSlot, Fees, FeesSpec};
48pub use math::number::Number;
49pub use math::wad::{
50    compute_fee_shares, compute_fee_shares_from_assets, compute_management_fee_shares,
51    mul_div_ceil, mul_div_floor, mul_wad_floor, total_assets_for_fee_accrual, Wad, MAX_FEE_WAD,
52    MAX_MANAGEMENT_FEE_WAD, MAX_PERFORMANCE_FEE_WAD, YEAR_NS,
53};
54pub use restrictions::{RestrictionKind, RestrictionMode, Restrictions};
55pub use state::escrow::{
56    apply_settlement, can_apply_settlement, compute_escrow_stats, find_by_owner, is_stale,
57    settle_proportional, settle_proportional_raw, total_burn, total_refund, EscrowEntry,
58    EscrowSettlement, EscrowStats, SettlementResult,
59};
60pub use state::op_state::{
61    AllocatingState, AllocationPlanEntry, IdleState, OpState, PayoutState, RefreshingState,
62    TargetId, WithdrawingState,
63};
64pub use state::queue::{
65    can_enqueue, can_partially_satisfy, can_satisfy_withdrawal, compute_full_withdrawal,
66    compute_idle_settlement, compute_partial_withdrawal, compute_queue_status, compute_settlement,
67    compute_settlement_by_price, count_satisfiable, find_request_status, is_past_cooldown,
68    is_valid_withdrawal_amount, PendingWithdrawal, QueueError, QueueStatus, WithdrawQueue,
69    WithdrawalRequestStatus, WithdrawalResult, DEFAULT_COOLDOWN_NS, MAX_PENDING, MAX_QUEUE_LENGTH,
70    MIN_WITHDRAWAL_ASSETS,
71};
72pub use state::vault::{FeeAccrualAnchor, VaultConfig, VaultState};
73pub use transitions::{
74    allocation_step_callback, complete_allocation, complete_refresh, payout_complete,
75    refresh_step_callback, start_allocation, start_refresh, start_withdrawal, stop_withdrawal,
76    withdrawal_collected, withdrawal_settled, withdrawal_step_callback, TransitionError,
77    TransitionRes, TransitionResult, WithdrawalRequest,
78};
79
80#[cfg(kani)]
81mod kani_proofs {
82    use alloc::{vec, vec::Vec};
83
84    use super::*;
85    #[cfg(feature = "action-recovery")]
86    use crate::actions::plan_emergency_reset;
87    use crate::actions::{
88        apply_payout_settlement, apply_withdrawal_request_plan, pending_withdrawal_head,
89        plan_payout_settlement, validate_queue_head, withdrawal_request_from_head,
90        WithdrawalRequestPlan,
91    };
92    use crate::effects::KernelEffect;
93
94    const MAX_AMOUNT: u128 = 32;
95    const OWNER: Address = Address([0x11; 32]);
96    const RECEIVER: Address = Address([0x22; 32]);
97    const SELF: Address = Address([0x33; 32]);
98    const SECOND_OWNER: Address = Address([0x44; 32]);
99    const SECOND_RECEIVER: Address = Address([0x55; 32]);
100
101    fn bounded_amount() -> u128 {
102        let amount = kani::any::<u128>();
103        kani::assume(amount <= MAX_AMOUNT);
104        amount
105    }
106
107    fn nonzero_bounded_amount() -> u128 {
108        let amount = bounded_amount();
109        kani::assume(amount > 0);
110        amount
111    }
112
113    fn zero_fee_config() -> VaultConfig {
114        VaultConfig {
115            fees: FeesSpec::zero(),
116            min_withdrawal_assets: 0,
117            withdrawal_cooldown_ns: 0,
118            max_pending_withdrawals: 3,
119            paused: false,
120            virtual_shares: 0,
121            virtual_assets: 0,
122        }
123    }
124
125    #[cfg(feature = "action-refresh-fees")]
126    fn active_fee_config() -> VaultConfig {
127        VaultConfig {
128            fees: FeesSpec::new(
129                FeeSlot::new(Wad::one() / 10, Address([0x66; 32])),
130                FeeSlot::zero(),
131                None,
132            ),
133            min_withdrawal_assets: 0,
134            withdrawal_cooldown_ns: 0,
135            max_pending_withdrawals: 3,
136            paused: false,
137            virtual_shares: 0,
138            virtual_assets: 0,
139        }
140    }
141
142    fn assert_accounting_invariant(state: &VaultState) {
143        assert!(state.check_invariant());
144        assert_eq!(
145            state.total_assets,
146            state.idle_assets + state.external_assets
147        );
148    }
149
150    fn assert_asset_sum(state: &VaultState) {
151        assert_eq!(
152            state.total_assets,
153            state.idle_assets + state.external_assets
154        );
155    }
156
157    fn assert_address_eq(left: Address, right: Address) {
158        assert_eq!(left.0[0], right.0[0]);
159        assert_eq!(left.0[1], right.0[1]);
160        assert_eq!(left.0[2], right.0[2]);
161        assert_eq!(left.0[3], right.0[3]);
162        assert_eq!(left.0[4], right.0[4]);
163        assert_eq!(left.0[5], right.0[5]);
164        assert_eq!(left.0[6], right.0[6]);
165        assert_eq!(left.0[7], right.0[7]);
166        assert_eq!(left.0[8], right.0[8]);
167        assert_eq!(left.0[9], right.0[9]);
168        assert_eq!(left.0[10], right.0[10]);
169        assert_eq!(left.0[11], right.0[11]);
170        assert_eq!(left.0[12], right.0[12]);
171        assert_eq!(left.0[13], right.0[13]);
172        assert_eq!(left.0[14], right.0[14]);
173        assert_eq!(left.0[15], right.0[15]);
174        assert_eq!(left.0[16], right.0[16]);
175        assert_eq!(left.0[17], right.0[17]);
176        assert_eq!(left.0[18], right.0[18]);
177        assert_eq!(left.0[19], right.0[19]);
178        assert_eq!(left.0[20], right.0[20]);
179        assert_eq!(left.0[21], right.0[21]);
180        assert_eq!(left.0[22], right.0[22]);
181        assert_eq!(left.0[23], right.0[23]);
182        assert_eq!(left.0[24], right.0[24]);
183        assert_eq!(left.0[25], right.0[25]);
184        assert_eq!(left.0[26], right.0[26]);
185        assert_eq!(left.0[27], right.0[27]);
186        assert_eq!(left.0[28], right.0[28]);
187        assert_eq!(left.0[29], right.0[29]);
188        assert_eq!(left.0[30], right.0[30]);
189        assert_eq!(left.0[31], right.0[31]);
190    }
191
192    fn bounded_state() -> VaultState {
193        let idle = bounded_amount();
194        let external = bounded_amount();
195        let shares = bounded_amount();
196        VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO)
197    }
198
199    fn allocation_plan(first: u128, second: u128) -> Vec<AllocationPlanEntry> {
200        vec![
201            AllocationPlanEntry::new(0, first),
202            AllocationPlanEntry::new(1, second),
203        ]
204    }
205
206    fn enqueue_withdrawal(
207        state: &mut VaultState,
208        owner: Address,
209        receiver: Address,
210        shares: u128,
211        expected_assets: u128,
212        requested_at_ns: TimestampNs,
213    ) -> u64 {
214        state
215            .withdraw_queue
216            .enqueue(owner, receiver, shares, expected_assets, requested_at_ns, 3)
217            .unwrap()
218    }
219
220    fn assert_transfer_shares_effect(
221        effect: &KernelEffect,
222        expected_from: Address,
223        expected_to: Address,
224        expected_shares: u128,
225    ) {
226        match effect {
227            KernelEffect::TransferShares { from, to, shares } => {
228                assert_address_eq(*from, expected_from);
229                assert_address_eq(*to, expected_to);
230                assert_eq!(*shares, expected_shares);
231            }
232            _ => panic!("expected transfer shares effect"),
233        }
234    }
235
236    fn assert_emit_event_effect(effect: &KernelEffect) {
237        match effect {
238            KernelEffect::EmitEvent { .. } => {}
239            _ => panic!("expected emit event effect"),
240        }
241    }
242
243    fn assert_refund_owner_is_owner(refund_owner: Option<Address>) {
244        match refund_owner {
245            Some(owner) => assert_address_eq(owner, OWNER),
246            None => panic!("expected refund owner"),
247        }
248    }
249
250    #[kani::proof]
251    fn bounded_initial_state_preserves_total_asset_invariant() {
252        let idle = bounded_amount();
253        let external = bounded_amount();
254        let shares = bounded_amount();
255
256        let state =
257            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
258
259        assert!(state.check_invariant());
260        assert_eq!(
261            state.total_assets,
262            state.idle_assets + state.external_assets
263        );
264        assert_eq!(state.total_shares, shares);
265        assert_eq!(state.withdraw_queue.status().length, 0);
266    }
267
268    #[kani::proof]
269    fn restore_to_idle_preserves_total_asset_invariant() {
270        let idle = bounded_amount();
271        let external = bounded_amount();
272        let restored = bounded_amount();
273        let shares = bounded_amount();
274
275        let mut state =
276            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
277        state.restore_to_idle(restored);
278
279        assert!(state.check_invariant());
280        assert_eq!(state.idle_assets, idle + restored);
281        assert_eq!(state.external_assets, external);
282        assert_eq!(state.total_assets, idle + external + restored);
283    }
284
285    #[kani::proof]
286    fn withdrawal_queue_enqueue_preserves_cached_escrow_and_claimability() {
287        let shares = nonzero_bounded_amount();
288        let expected_assets = bounded_amount();
289        let mut queue = WithdrawQueue::new();
290
291        let id = queue
292            .enqueue(
293                OWNER,
294                RECEIVER,
295                shares,
296                expected_assets,
297                TimestampNs::ZERO,
298                3,
299            )
300            .unwrap();
301
302        let status = queue.status();
303        assert_eq!(id, 0);
304        assert!(queue.check_invariants_with_max(3));
305        assert_eq!(status.length, 1);
306        assert_eq!(status.total_escrow_shares, shares);
307        assert_eq!(status.total_expected_assets, expected_assets);
308        assert!(queue.contains(id));
309        assert!(queue.head().is_some());
310    }
311
312    #[kani::proof]
313    #[kani::unwind(8)]
314    fn two_entry_withdrawal_queue_preserves_cached_escrow_and_claimability() {
315        let first_shares = nonzero_bounded_amount();
316        let second_shares = nonzero_bounded_amount();
317        let first_expected_assets = bounded_amount();
318        let second_expected_assets = bounded_amount();
319        let mut queue = WithdrawQueue::new();
320
321        let first_id = queue
322            .enqueue(
323                OWNER,
324                RECEIVER,
325                first_shares,
326                first_expected_assets,
327                TimestampNs::ZERO,
328                3,
329            )
330            .unwrap();
331        let second_id = queue
332            .enqueue(
333                RECEIVER,
334                OWNER,
335                second_shares,
336                second_expected_assets,
337                TimestampNs::ZERO,
338                3,
339            )
340            .unwrap();
341
342        let status = queue.status();
343        let first = queue
344            .get(first_id)
345            .expect("first withdrawal should be queued");
346        let second = queue
347            .get(second_id)
348            .expect("second withdrawal should be queued");
349
350        assert_eq!(first_id, 0);
351        assert_eq!(second_id, 1);
352        assert!(queue.check_invariants_with_max(3));
353        assert_eq!(status.length, 2);
354        assert_eq!(status.total_escrow_shares, first_shares + second_shares);
355        assert_eq!(
356            status.total_expected_assets,
357            first_expected_assets + second_expected_assets
358        );
359        assert!(queue.contains(first_id));
360        assert!(queue.contains(second_id));
361        assert_eq!(queue.head().map(|(id, _)| id), Some(first_id));
362        assert_eq!(first.escrow_shares, first_shares);
363        assert_eq!(first.expected_assets, first_expected_assets);
364        assert_eq!(second.escrow_shares, second_shares);
365        assert_eq!(second.expected_assets, second_expected_assets);
366    }
367
368    #[kani::proof]
369    #[kani::unwind(8)]
370    fn two_entry_withdrawal_queue_dequeues_fifo_and_preserves_cache() {
371        let first_shares = nonzero_bounded_amount();
372        let second_shares = nonzero_bounded_amount();
373        let first_expected_assets = bounded_amount();
374        let second_expected_assets = bounded_amount();
375        let mut queue = WithdrawQueue::new();
376
377        let first_id = queue
378            .enqueue(
379                OWNER,
380                RECEIVER,
381                first_shares,
382                first_expected_assets,
383                TimestampNs::ZERO,
384                3,
385            )
386            .unwrap();
387        let second_id = queue
388            .enqueue(
389                RECEIVER,
390                OWNER,
391                second_shares,
392                second_expected_assets,
393                TimestampNs::ZERO,
394                3,
395            )
396            .unwrap();
397
398        let (dequeued_id, dequeued) = queue.dequeue().expect("first withdrawal should dequeue");
399        let status = queue.status();
400
401        assert_eq!(dequeued_id, first_id);
402        assert_eq!(dequeued.escrow_shares, first_shares);
403        assert_eq!(dequeued.expected_assets, first_expected_assets);
404        assert!(queue.check_invariants_with_max(3));
405        assert_eq!(status.length, 1);
406        assert_eq!(status.total_escrow_shares, second_shares);
407        assert_eq!(status.total_expected_assets, second_expected_assets);
408        assert!(!queue.contains(first_id));
409        assert!(queue.contains(second_id));
410        assert_eq!(queue.head().map(|(id, _)| id), Some(second_id));
411    }
412
413    #[kani::proof]
414    #[kani::unwind(40)]
415    fn withdrawal_request_plan_preserves_accounting_and_enqueues_exact_escrow() {
416        let idle = bounded_amount();
417        let external = bounded_amount();
418        let total_shares = nonzero_bounded_amount();
419        let shares = nonzero_bounded_amount();
420        let expected_assets = bounded_amount();
421        kani::assume(idle + external <= MAX_AMOUNT);
422        let config = zero_fee_config();
423        let state = VaultState::with_initial(
424            idle + external,
425            total_shares,
426            idle,
427            external,
428            TimestampNs::ZERO,
429        );
430        let before = state.clone();
431        let plan = WithdrawalRequestPlan {
432            owner: RECEIVER,
433            receiver: OWNER,
434            shares,
435            expected_assets,
436        };
437
438        let requested =
439            apply_withdrawal_request_plan(state, &config, &SELF, plan, TimestampNs::ZERO).unwrap();
440
441        assert!(requested.state.op_state.is_idle());
442        assert_eq!(requested.state.idle_assets, before.idle_assets);
443        assert_eq!(requested.state.external_assets, before.external_assets);
444        assert_eq!(requested.state.total_assets, before.total_assets);
445        assert_eq!(requested.state.total_shares, before.total_shares);
446        assert_eq!(requested.state.next_op_id, before.next_op_id);
447        assert_eq!(requested.state.withdraw_queue.status().length, 1);
448        assert_eq!(
449            requested.state.withdraw_queue.status().total_escrow_shares,
450            shares
451        );
452        assert_eq!(
453            requested
454                .state
455                .withdraw_queue
456                .status()
457                .total_expected_assets,
458            expected_assets
459        );
460        let (request_id, head) = requested.state.withdraw_queue.head().unwrap();
461        assert_eq!(request_id, 0);
462        assert_address_eq(head.owner, RECEIVER);
463        assert_address_eq(head.receiver, OWNER);
464        assert_eq!(head.escrow_shares, shares);
465        assert_eq!(head.expected_assets, expected_assets);
466        assert_eq!(requested.effects.len(), 2);
467        assert_transfer_shares_effect(&requested.effects[0], RECEIVER, SELF, shares);
468        assert_emit_event_effect(&requested.effects[1]);
469        assert_asset_sum(&requested.state);
470    }
471
472    #[kani::proof]
473    #[kani::unwind(40)]
474    fn post_deposit_request_withdraw_preserves_accounting_and_escrows_previewed_shares() {
475        let deposited_assets = nonzero_bounded_amount();
476        let minted_shares = deposited_assets;
477        let config = zero_fee_config();
478        let post_deposit = VaultState::with_initial(
479            deposited_assets,
480            minted_shares,
481            deposited_assets,
482            0,
483            TimestampNs::from_nanos(1),
484        );
485        let post_deposit_idle_assets = post_deposit.idle_assets;
486        let post_deposit_external_assets = post_deposit.external_assets;
487        let post_deposit_total_assets = post_deposit.total_assets;
488        let post_deposit_total_shares = post_deposit.total_shares;
489        let post_deposit_next_op_id = post_deposit.next_op_id;
490        let expected_assets = deposited_assets;
491        let request_plan = WithdrawalRequestPlan {
492            owner: RECEIVER,
493            receiver: OWNER,
494            shares: minted_shares,
495            expected_assets,
496        };
497
498        let requested = apply_withdrawal_request_plan(
499            post_deposit,
500            &config,
501            &SELF,
502            request_plan,
503            TimestampNs::from_nanos(2),
504        )
505        .unwrap();
506
507        assert!(requested.state.op_state.is_idle());
508        assert_eq!(requested.state.idle_assets, post_deposit_idle_assets);
509        assert_eq!(
510            requested.state.external_assets,
511            post_deposit_external_assets
512        );
513        assert_eq!(requested.state.total_assets, post_deposit_total_assets);
514        assert_eq!(requested.state.total_shares, post_deposit_total_shares);
515        assert_eq!(requested.state.next_op_id, post_deposit_next_op_id);
516        assert_eq!(requested.state.withdraw_queue.status().length, 1);
517        assert_eq!(
518            requested.state.withdraw_queue.status().total_escrow_shares,
519            minted_shares
520        );
521        assert_eq!(
522            requested
523                .state
524                .withdraw_queue
525                .status()
526                .total_expected_assets,
527            expected_assets
528        );
529        let (request_id, head) = requested.state.withdraw_queue.head().unwrap();
530        assert_eq!(request_id, 0);
531        assert_address_eq(head.owner, RECEIVER);
532        assert_address_eq(head.receiver, OWNER);
533        assert_eq!(head.escrow_shares, minted_shares);
534        assert_eq!(head.expected_assets, expected_assets);
535        assert_eq!(requested.effects.len(), 2);
536        assert_transfer_shares_effect(&requested.effects[0], RECEIVER, SELF, minted_shares);
537        assert_emit_event_effect(&requested.effects[1]);
538        assert_asset_sum(&requested.state);
539    }
540
541    #[cfg(feature = "action-sync-external")]
542    #[kani::proof]
543    fn rebalance_withdraw_conserves_total_assets_and_moves_external_to_idle() {
544        let idle = bounded_amount();
545        let external = bounded_amount();
546        let shares = bounded_amount();
547        let amount = bounded_amount();
548        kani::assume(amount <= external);
549
550        let state =
551            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
552        let before_total_assets = state.total_assets;
553        let before_total_shares = state.total_shares;
554
555        let result = match apply_action(
556            state,
557            &zero_fee_config(),
558            None,
559            &SELF,
560            KernelAction::rebalance_withdraw(0, amount, TimestampNs::ZERO),
561        ) {
562            Ok(result) => result,
563            Err(_) => panic!("bounded rebalance withdraw should succeed"),
564        };
565
566        assert_eq!(
567            result.state.total_assets,
568            result.state.idle_assets + result.state.external_assets
569        );
570        assert_eq!(result.state.total_assets, before_total_assets);
571        assert_eq!(result.state.total_shares, before_total_shares);
572        assert_eq!(result.state.idle_assets, idle + amount);
573        assert_eq!(result.state.external_assets, external - amount);
574    }
575
576    #[cfg(feature = "action-sync-external")]
577    #[kani::proof]
578    fn sync_external_assets_preserves_total_as_idle_plus_external() {
579        let idle = bounded_amount();
580        let external = bounded_amount();
581        let synced_external = bounded_amount();
582        let shares = bounded_amount();
583        let op_id = 7;
584
585        let mut state =
586            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
587        state.op_state = OpState::Allocating(AllocatingState {
588            op_id,
589            index: 0,
590            remaining: 0,
591            plan: Vec::new(),
592        });
593
594        let result = match apply_action(
595            state,
596            &zero_fee_config(),
597            None,
598            &SELF,
599            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
600        ) {
601            Ok(result) => result,
602            Err(_) => panic!("bounded sync external assets should succeed"),
603        };
604
605        assert_eq!(
606            result.state.total_assets,
607            result.state.idle_assets + result.state.external_assets
608        );
609        assert_eq!(result.state.idle_assets, idle);
610        assert_eq!(result.state.external_assets, synced_external);
611        assert_eq!(result.state.total_assets, idle + synced_external);
612        assert_eq!(result.state.total_shares, shares);
613    }
614
615    #[cfg(feature = "action-sync-external")]
616    #[kani::proof]
617    fn bounded_sync_then_rebalance_conserves_accounting_across_actions() {
618        let idle = bounded_amount();
619        let external = bounded_amount();
620        let shares = bounded_amount();
621        let synced_external = bounded_amount();
622        let rebalance_amount = bounded_amount();
623        let op_id = 9;
624        kani::assume(rebalance_amount <= synced_external);
625
626        let mut state =
627            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
628        state.op_state = OpState::Allocating(AllocatingState {
629            op_id,
630            index: 0,
631            remaining: 0,
632            plan: Vec::new(),
633        });
634
635        let synced = match apply_action(
636            state,
637            &zero_fee_config(),
638            None,
639            &SELF,
640            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
641        ) {
642            Ok(result) => result.state,
643            Err(_) => panic!("bounded sync external assets should succeed"),
644        };
645
646        let rebalanced = match apply_action(
647            synced,
648            &zero_fee_config(),
649            None,
650            &SELF,
651            KernelAction::rebalance_withdraw(op_id, rebalance_amount, TimestampNs::ZERO),
652        ) {
653            Ok(result) => result.state,
654            Err(_) => panic!("bounded rebalance withdraw should succeed after sync"),
655        };
656
657        assert_eq!(
658            rebalanced.total_assets,
659            rebalanced.idle_assets + rebalanced.external_assets
660        );
661        assert_eq!(rebalanced.total_shares, shares);
662        assert_eq!(rebalanced.idle_assets, idle + rebalance_amount);
663        assert_eq!(
664            rebalanced.external_assets,
665            synced_external - rebalance_amount
666        );
667        assert_eq!(rebalanced.total_assets, idle + synced_external);
668    }
669
670    #[cfg(all(
671        feature = "action-allocation-lifecycle",
672        feature = "action-sync-external",
673        feature = "action-recovery"
674    ))]
675    #[kani::proof]
676    #[kani::unwind(8)]
677    fn allocation_partial_sync_then_abort_restores_unallocated_assets() {
678        let idle = nonzero_bounded_amount();
679        let external = bounded_amount();
680        let shares = bounded_amount();
681        let first = nonzero_bounded_amount();
682        let second = bounded_amount();
683        kani::assume(first + second <= idle);
684
685        let op_id = 11;
686        let state =
687            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
688        let started = apply_action(
689            state,
690            &zero_fee_config(),
691            None,
692            &SELF,
693            KernelAction::begin_allocating(
694                op_id,
695                allocation_plan(first, second),
696                TimestampNs::ZERO,
697            ),
698        )
699        .unwrap()
700        .state;
701
702        let stepped = allocation_step_callback(started.op_state.clone(), true, first, op_id)
703            .unwrap()
704            .new_state;
705        let mut after_step = started;
706        after_step.op_state = stepped;
707
708        let synced = apply_action(
709            after_step,
710            &zero_fee_config(),
711            None,
712            &SELF,
713            KernelAction::sync_external_assets(external + first, op_id, TimestampNs::ZERO),
714        )
715        .unwrap()
716        .state;
717
718        let result = apply_action(
719            synced,
720            &zero_fee_config(),
721            None,
722            &SELF,
723            KernelAction::abort_allocating(op_id),
724        )
725        .unwrap();
726
727        assert!(result.state.op_state.is_idle());
728        assert_asset_sum(&result.state);
729        assert_eq!(result.state.idle_assets, idle - first);
730        assert_eq!(result.state.external_assets, external + first);
731        assert_eq!(result.state.total_assets, idle + external);
732        assert_eq!(result.state.total_shares, shares);
733        assert_eq!(result.state.withdraw_queue.status().length, 0);
734    }
735
736    #[cfg(all(
737        feature = "action-allocation-lifecycle",
738        feature = "action-sync-external"
739    ))]
740    #[kani::proof]
741    #[kani::unwind(8)]
742    fn allocation_full_sync_then_finish_conserves_assets() {
743        let idle = nonzero_bounded_amount();
744        let external = bounded_amount();
745        let shares = bounded_amount();
746        let first = nonzero_bounded_amount();
747        let second = bounded_amount();
748        kani::assume(first + second <= idle);
749
750        let op_id = 12;
751        let state =
752            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
753        let started = apply_action(
754            state,
755            &zero_fee_config(),
756            None,
757            &SELF,
758            KernelAction::begin_allocating(
759                op_id,
760                allocation_plan(first, second),
761                TimestampNs::ZERO,
762            ),
763        )
764        .unwrap()
765        .state;
766
767        let stepped_once = allocation_step_callback(started.op_state.clone(), true, first, op_id)
768            .unwrap()
769            .new_state;
770        let stepped_twice = if second > 0 {
771            allocation_step_callback(stepped_once, true, second, op_id)
772                .unwrap()
773                .new_state
774        } else {
775            stepped_once
776        };
777        let mut after_steps = started;
778        after_steps.op_state = stepped_twice;
779
780        let synced = apply_action(
781            after_steps,
782            &zero_fee_config(),
783            None,
784            &SELF,
785            KernelAction::sync_external_assets(external + first + second, op_id, TimestampNs::ZERO),
786        )
787        .unwrap()
788        .state;
789
790        let result = apply_action(
791            synced,
792            &zero_fee_config(),
793            None,
794            &SELF,
795            KernelAction::finish_allocating(op_id, TimestampNs::ZERO),
796        )
797        .unwrap();
798
799        assert!(result.state.op_state.is_idle());
800        assert_asset_sum(&result.state);
801        assert_eq!(result.state.idle_assets, idle - first - second);
802        assert_eq!(result.state.external_assets, external + first + second);
803        assert_eq!(result.state.total_assets, idle + external);
804        assert_eq!(result.state.total_shares, shares);
805    }
806
807    #[cfg(all(
808        feature = "action-allocation-lifecycle",
809        feature = "action-sync-external",
810        feature = "action-recovery"
811    ))]
812    #[kani::proof]
813    fn allocation_wrong_op_id_is_rejected_without_progress() {
814        let mut state = bounded_state();
815        let op_id = 13;
816        let wrong_op_id = 14;
817        state.op_state = OpState::Allocating(AllocatingState {
818            op_id,
819            index: 0,
820            remaining: 1,
821            plan: allocation_plan(1, 0),
822        });
823        let baseline = state.clone();
824
825        assert!(allocation_step_callback(state.op_state.clone(), true, 1, wrong_op_id).is_err());
826        assert!(apply_action(
827            state.clone(),
828            &zero_fee_config(),
829            None,
830            &SELF,
831            KernelAction::sync_external_assets(1, wrong_op_id, TimestampNs::ZERO),
832        )
833        .is_err());
834        assert!(apply_action(
835            state.clone(),
836            &zero_fee_config(),
837            None,
838            &SELF,
839            KernelAction::finish_allocating(wrong_op_id, TimestampNs::ZERO),
840        )
841        .is_err());
842        assert!(apply_action(
843            state.clone(),
844            &zero_fee_config(),
845            None,
846            &SELF,
847            KernelAction::abort_allocating(wrong_op_id),
848        )
849        .is_err());
850        assert!(state == baseline);
851    }
852
853    #[kani::proof]
854    fn withdrawal_collection_preserves_collected_plus_remaining() {
855        let amount = nonzero_bounded_amount();
856        let first_collect = bounded_amount();
857        let burn_shares = bounded_amount();
858        let escrow_shares = nonzero_bounded_amount();
859        kani::assume(first_collect <= amount);
860        kani::assume(burn_shares <= escrow_shares);
861
862        let op_id = 31;
863        let request = WithdrawalRequest {
864            op_id,
865            request_id: 0,
866            amount,
867            receiver: RECEIVER,
868            owner: OWNER,
869            escrow_shares,
870        };
871
872        let started = start_withdrawal(OpState::Idle, request).unwrap().new_state;
873        let stepped = withdrawal_step_callback(started, op_id, first_collect)
874            .unwrap()
875            .new_state;
876        let withdrawing = stepped.as_withdrawing().unwrap();
877        assert_eq!(withdrawing.collected + withdrawing.remaining, amount);
878
879        if withdrawing.remaining > 0 {
880            assert!(withdrawal_collected(stepped.clone(), op_id, burn_shares).is_err());
881        }
882
883        let completed = withdrawal_step_callback(stepped, op_id, amount - first_collect)
884            .unwrap()
885            .new_state;
886        let payout = withdrawal_collected(completed, op_id, burn_shares)
887            .unwrap()
888            .new_state;
889        let payout = payout.as_payout().unwrap();
890        assert_eq!(payout.amount, amount);
891        assert_eq!(payout.burn_shares, burn_shares);
892        assert!(payout.burn_shares <= payout.escrow_shares);
893    }
894
895    #[kani::proof]
896    #[kani::unwind(40)]
897    fn withdrawal_queue_head_validation_requires_exact_identity_fields() {
898        let mut state = VaultState::with_initial(16, 16, 16, 0, TimestampNs::ZERO);
899        let first_id = enqueue_withdrawal(&mut state, OWNER, RECEIVER, 3, 5, TimestampNs::ZERO);
900
901        assert!(
902            validate_queue_head(&state.withdraw_queue, first_id, &OWNER, &RECEIVER, 3,).is_ok()
903        );
904        assert!(
905            validate_queue_head(&state.withdraw_queue, first_id + 1, &OWNER, &RECEIVER, 3,)
906                .is_err()
907        );
908        assert!(
909            validate_queue_head(&state.withdraw_queue, first_id, &SECOND_OWNER, &RECEIVER, 3,)
910                .is_err()
911        );
912        assert!(
913            validate_queue_head(&state.withdraw_queue, first_id, &OWNER, &SECOND_RECEIVER, 3,)
914                .is_err()
915        );
916        assert!(
917            validate_queue_head(&state.withdraw_queue, first_id, &OWNER, &RECEIVER, 4,).is_err()
918        );
919        assert_eq!(
920            state.withdraw_queue.head().map(|(id, _)| id),
921            Some(first_id)
922        );
923    }
924
925    #[kani::proof]
926    #[kani::unwind(40)]
927    fn withdrawal_queue_head_validation_rejects_later_fifo_entry() {
928        let mut state = VaultState::with_initial(16, 16, 16, 0, TimestampNs::ZERO);
929        let first_id = enqueue_withdrawal(&mut state, OWNER, RECEIVER, 3, 5, TimestampNs::ZERO);
930        let second_id = enqueue_withdrawal(
931            &mut state,
932            SECOND_OWNER,
933            SECOND_RECEIVER,
934            7,
935            11,
936            TimestampNs::ZERO,
937        );
938        let before = state.withdraw_queue.status();
939
940        assert!(
941            validate_queue_head(&state.withdraw_queue, first_id, &OWNER, &RECEIVER, 3,).is_ok()
942        );
943        assert!(validate_queue_head(
944            &state.withdraw_queue,
945            second_id,
946            &SECOND_OWNER,
947            &SECOND_RECEIVER,
948            7,
949        )
950        .is_err());
951        assert_eq!(
952            state.withdraw_queue.head().map(|(id, _)| id),
953            Some(first_id)
954        );
955        assert_eq!(state.withdraw_queue.status().length, before.length);
956        assert_eq!(
957            state.withdraw_queue.status().total_escrow_shares,
958            before.total_escrow_shares
959        );
960        assert_eq!(
961            state.withdraw_queue.status().total_expected_assets,
962            before.total_expected_assets
963        );
964    }
965
966    #[kani::proof]
967    #[kani::unwind(40)]
968    fn withdrawal_fifo_head_maps_to_started_withdrawal_request() {
969        let mut state = VaultState::with_initial(16, 16, 16, 0, TimestampNs::ZERO);
970        let first_id = enqueue_withdrawal(&mut state, OWNER, RECEIVER, 3, 5, TimestampNs::ZERO);
971
972        let head = pending_withdrawal_head(&state).unwrap();
973        assert_eq!(head.id, first_id);
974        assert_address_eq(head.owner, OWNER);
975        assert_address_eq(head.receiver, RECEIVER);
976        assert_eq!(head.escrow_shares, 3);
977        assert_eq!(head.expected_assets, 5);
978
979        let request = withdrawal_request_from_head(&mut state, head);
980        assert_eq!(request.request_id, first_id);
981        assert_address_eq(request.owner, OWNER);
982        assert_address_eq(request.receiver, RECEIVER);
983        assert_eq!(request.escrow_shares, 3);
984        assert_eq!(request.amount, 5);
985        assert_eq!(state.withdraw_queue.status().length, 1);
986
987        let started = start_withdrawal(OpState::Idle, request).unwrap().new_state;
988        let withdrawing = started.as_withdrawing().unwrap();
989        assert_eq!(withdrawing.request_id, first_id);
990        assert_address_eq(withdrawing.owner, OWNER);
991        assert_address_eq(withdrawing.receiver, RECEIVER);
992        assert_eq!(withdrawing.escrow_shares, 3);
993        assert_eq!(withdrawing.remaining, 5);
994    }
995
996    #[kani::proof]
997    #[kani::unwind(40)]
998    fn payout_queue_head_dequeues_once_before_settlement() {
999        let mut queue = WithdrawQueue::new();
1000        let first_id = queue
1001            .enqueue(OWNER, RECEIVER, 3, 5, TimestampNs::ZERO, 3)
1002            .unwrap();
1003        let second_id = queue
1004            .enqueue(SECOND_OWNER, SECOND_RECEIVER, 7, 11, TimestampNs::ZERO, 3)
1005            .unwrap();
1006
1007        let (dequeued_id, dequeued) = queue.dequeue().unwrap();
1008        assert_eq!(dequeued_id, first_id);
1009        assert_address_eq(dequeued.owner, OWNER);
1010        assert_address_eq(dequeued.receiver, RECEIVER);
1011        assert_eq!(dequeued.escrow_shares, 3);
1012        assert_eq!(dequeued.expected_assets, 5);
1013        assert_eq!(queue.status().length, 1);
1014        assert_eq!(queue.status().total_escrow_shares, 7);
1015        assert_eq!(queue.status().total_expected_assets, 11);
1016        assert_eq!(queue.head().map(|(id, _)| id), Some(second_id));
1017    }
1018
1019    #[kani::proof]
1020    #[kani::unwind(40)]
1021    fn payout_success_settlement_conserves_assets_and_escrow() {
1022        let idle = nonzero_bounded_amount();
1023        let external = bounded_amount();
1024        let total_shares = nonzero_bounded_amount();
1025        let escrow_shares = nonzero_bounded_amount();
1026        let burn_shares = bounded_amount();
1027        let amount = bounded_amount();
1028        kani::assume(burn_shares <= escrow_shares);
1029        kani::assume(burn_shares <= total_shares);
1030        kani::assume(amount <= idle);
1031
1032        let op_id = 41;
1033        let mut state = VaultState::with_initial(
1034            idle + external,
1035            total_shares,
1036            idle,
1037            external,
1038            TimestampNs::ZERO,
1039        );
1040        let request_id = enqueue_withdrawal(
1041            &mut state,
1042            OWNER,
1043            RECEIVER,
1044            escrow_shares,
1045            amount,
1046            TimestampNs::ZERO,
1047        );
1048        let payout = PayoutState {
1049            op_id,
1050            request_id,
1051            receiver: RECEIVER,
1052            amount,
1053            owner: OWNER,
1054            escrow_shares,
1055            burn_shares,
1056        };
1057
1058        assert!(validate_queue_head(
1059            &state.withdraw_queue,
1060            payout.request_id,
1061            &payout.owner,
1062            &payout.receiver,
1063            payout.escrow_shares,
1064        )
1065        .is_ok());
1066        let (dequeued_id, dequeued) = state.withdraw_queue.dequeue().unwrap();
1067        assert_eq!(dequeued_id, request_id);
1068        assert_address_eq(dequeued.owner, OWNER);
1069        assert_address_eq(dequeued.receiver, RECEIVER);
1070        assert_eq!(dequeued.escrow_shares, escrow_shares);
1071        assert_eq!(state.withdraw_queue.status().length, 0);
1072
1073        let settlement = plan_payout_settlement(&payout, PayoutOutcome::Success).unwrap();
1074        let mut effects = Vec::new();
1075        apply_payout_settlement(&mut state, &payout, settlement, SELF, &mut effects).unwrap();
1076
1077        assert!(state.op_state.is_idle());
1078        assert_asset_sum(&state);
1079        assert!(settlement.success);
1080        assert_eq!(settlement.burn_shares, burn_shares);
1081        assert_eq!(settlement.refund_shares, escrow_shares - burn_shares);
1082        assert_eq!(
1083            settlement.burn_shares + settlement.refund_shares,
1084            escrow_shares
1085        );
1086        assert_eq!(settlement.completed_amount, amount);
1087        assert_eq!(state.idle_assets, idle - amount);
1088        assert_eq!(state.external_assets, external);
1089        assert_eq!(state.total_assets, idle + external - amount);
1090        assert_eq!(state.total_shares, total_shares - burn_shares);
1091        assert_eq!(state.withdraw_queue.status().length, 0);
1092    }
1093
1094    #[kani::proof]
1095    #[kani::unwind(40)]
1096    fn payout_failure_settlement_refunds_without_mutating_assets_or_shares_and_dequeues_head_once()
1097    {
1098        let idle = nonzero_bounded_amount();
1099        let external = bounded_amount();
1100        let total_shares = nonzero_bounded_amount();
1101        let escrow_shares = nonzero_bounded_amount();
1102        let burn_shares = bounded_amount();
1103        let amount = bounded_amount();
1104        kani::assume(burn_shares <= escrow_shares);
1105        kani::assume(amount <= idle);
1106
1107        let op_id = 42;
1108        let mut state = VaultState::with_initial(
1109            idle + external,
1110            total_shares,
1111            idle,
1112            external,
1113            TimestampNs::ZERO,
1114        );
1115        let request_id = enqueue_withdrawal(
1116            &mut state,
1117            OWNER,
1118            RECEIVER,
1119            escrow_shares,
1120            amount,
1121            TimestampNs::ZERO,
1122        );
1123        let payout = PayoutState {
1124            op_id,
1125            request_id,
1126            receiver: RECEIVER,
1127            amount,
1128            owner: OWNER,
1129            escrow_shares,
1130            burn_shares,
1131        };
1132
1133        assert!(validate_queue_head(
1134            &state.withdraw_queue,
1135            payout.request_id,
1136            &payout.owner,
1137            &payout.receiver,
1138            payout.escrow_shares,
1139        )
1140        .is_ok());
1141        let (dequeued_id, dequeued) = state.withdraw_queue.dequeue().unwrap();
1142        assert_eq!(dequeued_id, request_id);
1143        assert_address_eq(dequeued.owner, OWNER);
1144        assert_address_eq(dequeued.receiver, RECEIVER);
1145        assert_eq!(dequeued.escrow_shares, escrow_shares);
1146        assert_eq!(state.withdraw_queue.status().length, 0);
1147
1148        let settlement = plan_payout_settlement(&payout, PayoutOutcome::Failure).unwrap();
1149        let mut effects = Vec::new();
1150        apply_payout_settlement(&mut state, &payout, settlement, SELF, &mut effects).unwrap();
1151
1152        assert!(state.op_state.is_idle());
1153        assert_asset_sum(&state);
1154        assert!(!settlement.success);
1155        assert_eq!(settlement.burn_shares, 0);
1156        assert_eq!(settlement.refund_shares, escrow_shares);
1157        assert_eq!(settlement.completed_amount, 0);
1158        assert_eq!(state.idle_assets, idle);
1159        assert_eq!(state.external_assets, external);
1160        assert_eq!(state.total_assets, idle + external);
1161        assert_eq!(state.total_shares, total_shares);
1162    }
1163
1164    #[cfg(feature = "action-recovery")]
1165    #[kani::proof]
1166    #[kani::unwind(8)]
1167    fn emergency_reset_allocating_restores_remaining_assets_to_idle() {
1168        let idle = bounded_amount();
1169        let external = bounded_amount();
1170        let total_shares = bounded_amount();
1171        let remaining = bounded_amount();
1172        let op_id = 51;
1173
1174        let mut state = VaultState::with_initial(
1175            idle + external,
1176            total_shares,
1177            idle,
1178            external,
1179            TimestampNs::ZERO,
1180        );
1181        state.op_state = OpState::Allocating(AllocatingState {
1182            op_id,
1183            index: 0,
1184            remaining,
1185            plan: allocation_plan(remaining, 0),
1186        });
1187
1188        let result = plan_emergency_reset(state).unwrap();
1189
1190        assert!(result.state.op_state.is_idle());
1191        assert_eq!(result.state.idle_assets, idle + remaining);
1192        assert_eq!(result.state.external_assets, external);
1193        assert_eq!(result.state.total_assets, idle + external + remaining);
1194        assert_eq!(result.state.total_shares, total_shares);
1195        assert_eq!(result.state.withdraw_queue.status().length, 0);
1196        assert!(result.refund_owner.is_none());
1197        assert_eq!(result.refund_shares, 0);
1198        assert_eq!(
1199            result.state.fee_anchor.total_assets,
1200            result.state.total_assets
1201        );
1202        assert_asset_sum(&result.state);
1203    }
1204
1205    #[cfg(feature = "action-recovery")]
1206    #[kani::proof]
1207    #[kani::unwind(8)]
1208    fn emergency_reset_withdrawing_restores_collected_assets_and_refunds_escrow() {
1209        let idle = bounded_amount();
1210        let external = bounded_amount();
1211        let total_shares = nonzero_bounded_amount();
1212        let remaining = bounded_amount();
1213        let collected = bounded_amount();
1214        let escrow_shares = nonzero_bounded_amount();
1215        let op_id = 52;
1216
1217        let mut state = VaultState::with_initial(
1218            idle + external,
1219            total_shares,
1220            idle,
1221            external,
1222            TimestampNs::ZERO,
1223        );
1224        let request_id = enqueue_withdrawal(
1225            &mut state,
1226            OWNER,
1227            RECEIVER,
1228            escrow_shares,
1229            collected + remaining,
1230            TimestampNs::ZERO,
1231        );
1232        state.op_state = OpState::Withdrawing(WithdrawingState {
1233            op_id,
1234            request_id,
1235            index: 0,
1236            remaining,
1237            collected,
1238            receiver: RECEIVER,
1239            owner: OWNER,
1240            escrow_shares,
1241        });
1242
1243        let result = plan_emergency_reset(state).unwrap();
1244
1245        assert!(result.state.op_state.is_idle());
1246        assert_eq!(result.state.idle_assets, idle + collected);
1247        assert_eq!(result.state.external_assets, external);
1248        assert_eq!(result.state.total_assets, idle + external + collected);
1249        assert_eq!(result.state.total_shares, total_shares);
1250        assert_eq!(result.state.withdraw_queue.status().length, 0);
1251        assert_refund_owner_is_owner(result.refund_owner);
1252        assert_eq!(result.refund_shares, escrow_shares);
1253        assert_eq!(
1254            result.state.fee_anchor.total_assets,
1255            result.state.total_assets
1256        );
1257        assert_asset_sum(&result.state);
1258    }
1259
1260    #[cfg(feature = "action-recovery")]
1261    #[kani::proof]
1262    #[kani::unwind(8)]
1263    fn emergency_reset_payout_restores_payout_assets_and_refunds_escrow() {
1264        let idle = bounded_amount();
1265        let external = bounded_amount();
1266        let total_shares = nonzero_bounded_amount();
1267        let amount = bounded_amount();
1268        let escrow_shares = nonzero_bounded_amount();
1269        let burn_shares = bounded_amount();
1270        let op_id = 53;
1271        kani::assume(burn_shares <= escrow_shares);
1272
1273        let mut state = VaultState::with_initial(
1274            idle + external,
1275            total_shares,
1276            idle,
1277            external,
1278            TimestampNs::ZERO,
1279        );
1280        let request_id = enqueue_withdrawal(
1281            &mut state,
1282            OWNER,
1283            RECEIVER,
1284            escrow_shares,
1285            amount,
1286            TimestampNs::ZERO,
1287        );
1288        state.op_state = OpState::Payout(PayoutState {
1289            op_id,
1290            request_id,
1291            receiver: RECEIVER,
1292            amount,
1293            owner: OWNER,
1294            escrow_shares,
1295            burn_shares,
1296        });
1297
1298        let result = plan_emergency_reset(state).unwrap();
1299
1300        assert!(result.state.op_state.is_idle());
1301        assert_eq!(result.state.idle_assets, idle + amount);
1302        assert_eq!(result.state.external_assets, external);
1303        assert_eq!(result.state.total_assets, idle + external + amount);
1304        assert_eq!(result.state.total_shares, total_shares);
1305        assert_eq!(result.state.withdraw_queue.status().length, 0);
1306        assert_refund_owner_is_owner(result.refund_owner);
1307        assert_eq!(result.refund_shares, escrow_shares);
1308        assert_eq!(
1309            result.state.fee_anchor.total_assets,
1310            result.state.total_assets
1311        );
1312        assert_asset_sum(&result.state);
1313    }
1314
1315    #[cfg(feature = "action-recovery")]
1316    #[kani::proof]
1317    #[kani::unwind(8)]
1318    fn emergency_reset_refreshing_returns_idle_without_accounting_mutation() {
1319        let idle = bounded_amount();
1320        let external = bounded_amount();
1321        let total_shares = bounded_amount();
1322        let op_id = 54;
1323
1324        let mut state = VaultState::with_initial(
1325            idle + external,
1326            total_shares,
1327            idle,
1328            external,
1329            TimestampNs::ZERO,
1330        );
1331        let before = state.clone();
1332        state.op_state = OpState::Refreshing(RefreshingState {
1333            op_id,
1334            index: 1,
1335            plan: vec![7, 8],
1336        });
1337
1338        let result = plan_emergency_reset(state).unwrap();
1339
1340        assert!(result.state.op_state.is_idle());
1341        assert_eq!(result.state.idle_assets, before.idle_assets);
1342        assert_eq!(result.state.external_assets, before.external_assets);
1343        assert_eq!(result.state.total_assets, before.total_assets);
1344        assert_eq!(result.state.total_shares, before.total_shares);
1345        assert_eq!(
1346            result.state.withdraw_queue.status().length,
1347            before.withdraw_queue.status().length
1348        );
1349        assert!(result.refund_owner.is_none());
1350        assert_eq!(result.refund_shares, 0);
1351        assert_eq!(
1352            result.state.fee_anchor.total_assets,
1353            result.state.total_assets
1354        );
1355        assert_asset_sum(&result.state);
1356    }
1357
1358    #[cfg(feature = "action-sync-external")]
1359    #[kani::proof]
1360    #[kani::unwind(8)]
1361    fn sync_external_assets_allocating_only_mutates_external_and_total_assets() {
1362        let idle = bounded_amount();
1363        let external = bounded_amount();
1364        let synced_external = bounded_amount();
1365        let shares = bounded_amount();
1366        let op_id = 61;
1367
1368        let mut state =
1369            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1370        state.op_state = OpState::Allocating(AllocatingState {
1371            op_id,
1372            index: 1,
1373            remaining: 2,
1374            plan: allocation_plan(1, 1),
1375        });
1376
1377        let before_idle = state.idle_assets;
1378        let before_shares = state.total_shares;
1379        let before_queue = state.withdraw_queue.status();
1380        let before_next_op_id = state.next_op_id;
1381        let before_fee_anchor_total_assets = state.fee_anchor.total_assets;
1382        let before_fee_anchor_timestamp = state.fee_anchor.timestamp_ns;
1383        let result = apply_action(
1384            state,
1385            &zero_fee_config(),
1386            None,
1387            &SELF,
1388            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1389        )
1390        .unwrap();
1391
1392        assert_eq!(result.state.idle_assets, before_idle);
1393        assert_eq!(result.state.external_assets, synced_external);
1394        assert_eq!(result.state.total_assets, before_idle + synced_external);
1395        assert_eq!(result.state.total_shares, before_shares);
1396        assert_eq!(
1397            result.state.withdraw_queue.status().length,
1398            before_queue.length
1399        );
1400        assert_eq!(
1401            result.state.withdraw_queue.status().total_escrow_shares,
1402            before_queue.total_escrow_shares
1403        );
1404        assert_eq!(
1405            result.state.withdraw_queue.status().total_expected_assets,
1406            before_queue.total_expected_assets
1407        );
1408        assert_eq!(result.state.next_op_id, before_next_op_id);
1409        assert_eq!(
1410            result.state.fee_anchor.total_assets,
1411            before_fee_anchor_total_assets
1412        );
1413        assert!(result.state.fee_anchor.timestamp_ns == before_fee_anchor_timestamp);
1414        if let OpState::Allocating(alloc) = &result.state.op_state {
1415            assert_eq!(alloc.op_id, op_id);
1416            assert_eq!(alloc.index, 1);
1417            assert_eq!(alloc.remaining, 2);
1418        } else {
1419            panic!("sync must preserve allocating operation");
1420        }
1421        assert_asset_sum(&result.state);
1422    }
1423
1424    #[cfg(feature = "action-sync-external")]
1425    #[kani::proof]
1426    #[kani::unwind(8)]
1427    fn sync_external_assets_withdrawing_preserves_share_supply_queue_and_actor_fields() {
1428        let idle = bounded_amount();
1429        let external = bounded_amount();
1430        let synced_external = bounded_amount();
1431        let shares = bounded_amount();
1432        let op_id = 62;
1433
1434        let mut state =
1435            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1436        state.op_state = OpState::Withdrawing(WithdrawingState {
1437            op_id,
1438            request_id: 7,
1439            index: 1,
1440            remaining: 2,
1441            collected: 2,
1442            receiver: RECEIVER,
1443            owner: OWNER,
1444            escrow_shares: 3,
1445        });
1446
1447        let before_queue = state.withdraw_queue.status();
1448        let before_next_op_id = state.next_op_id;
1449        let result = apply_action(
1450            state,
1451            &zero_fee_config(),
1452            None,
1453            &SELF,
1454            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1455        )
1456        .unwrap();
1457
1458        assert_eq!(result.state.idle_assets, idle);
1459        assert_eq!(result.state.external_assets, synced_external);
1460        assert_eq!(result.state.total_assets, idle + synced_external);
1461        assert_eq!(result.state.total_shares, shares);
1462        assert_eq!(
1463            result.state.withdraw_queue.status().length,
1464            before_queue.length
1465        );
1466        assert_eq!(
1467            result.state.withdraw_queue.status().total_escrow_shares,
1468            before_queue.total_escrow_shares
1469        );
1470        assert_eq!(
1471            result.state.withdraw_queue.status().total_expected_assets,
1472            before_queue.total_expected_assets
1473        );
1474        assert_eq!(result.state.next_op_id, before_next_op_id);
1475        if let OpState::Withdrawing(withdraw) = &result.state.op_state {
1476            assert_eq!(withdraw.op_id, op_id);
1477            assert_eq!(withdraw.request_id, 7);
1478            assert_eq!(withdraw.index, 1);
1479            assert_eq!(withdraw.remaining, 2);
1480            assert_eq!(withdraw.collected, 2);
1481            assert_address_eq(withdraw.owner, OWNER);
1482            assert_address_eq(withdraw.receiver, RECEIVER);
1483            assert_eq!(withdraw.escrow_shares, 3);
1484        } else {
1485            panic!("sync must preserve withdrawing operation");
1486        }
1487        assert_asset_sum(&result.state);
1488    }
1489
1490    #[cfg(feature = "action-sync-external")]
1491    #[kani::proof]
1492    #[kani::unwind(8)]
1493    fn sync_external_assets_refreshing_only_mutates_external_and_total_assets() {
1494        let idle = bounded_amount();
1495        let external = bounded_amount();
1496        let synced_external = bounded_amount();
1497        let shares = bounded_amount();
1498        let op_id = 63;
1499
1500        let mut state =
1501            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1502        state.op_state = OpState::Refreshing(RefreshingState {
1503            op_id,
1504            index: 1,
1505            plan: vec![7, 8],
1506        });
1507
1508        let before_queue = state.withdraw_queue.status();
1509        let before_next_op_id = state.next_op_id;
1510        let result = apply_action(
1511            state,
1512            &zero_fee_config(),
1513            None,
1514            &SELF,
1515            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1516        )
1517        .unwrap();
1518
1519        assert_eq!(result.state.idle_assets, idle);
1520        assert_eq!(result.state.external_assets, synced_external);
1521        assert_eq!(result.state.total_assets, idle + synced_external);
1522        assert_eq!(result.state.total_shares, shares);
1523        assert_eq!(
1524            result.state.withdraw_queue.status().length,
1525            before_queue.length
1526        );
1527        assert_eq!(
1528            result.state.withdraw_queue.status().total_escrow_shares,
1529            before_queue.total_escrow_shares
1530        );
1531        assert_eq!(
1532            result.state.withdraw_queue.status().total_expected_assets,
1533            before_queue.total_expected_assets
1534        );
1535        assert_eq!(result.state.next_op_id, before_next_op_id);
1536        if let OpState::Refreshing(refresh) = &result.state.op_state {
1537            assert_eq!(refresh.op_id, op_id);
1538            assert_eq!(refresh.index, 1);
1539        } else {
1540            panic!("sync must preserve refreshing operation");
1541        }
1542        assert_asset_sum(&result.state);
1543    }
1544
1545    #[cfg(feature = "action-sync-external")]
1546    #[kani::proof]
1547    #[kani::unwind(8)]
1548    fn sync_external_assets_rejects_wrong_op_id_and_disallowed_states() {
1549        let idle = bounded_amount();
1550        let external = bounded_amount();
1551        let synced_external = bounded_amount();
1552        let shares = bounded_amount();
1553        let op_id = 64;
1554
1555        let mut allocating =
1556            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1557        allocating.op_state = OpState::Allocating(AllocatingState {
1558            op_id,
1559            index: 1,
1560            remaining: 2,
1561            plan: allocation_plan(1, 1),
1562        });
1563        assert!(apply_action(
1564            allocating,
1565            &zero_fee_config(),
1566            None,
1567            &SELF,
1568            KernelAction::sync_external_assets(synced_external, op_id + 1, TimestampNs::ZERO),
1569        )
1570        .is_err());
1571
1572        let idle_state =
1573            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1574        assert!(apply_action(
1575            idle_state,
1576            &zero_fee_config(),
1577            None,
1578            &SELF,
1579            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1580        )
1581        .is_err());
1582
1583        let mut payout_state =
1584            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1585        payout_state.op_state = OpState::Payout(PayoutState {
1586            op_id,
1587            request_id: 0,
1588            receiver: RECEIVER,
1589            amount: 1,
1590            owner: OWNER,
1591            escrow_shares: 1,
1592            burn_shares: 1,
1593        });
1594        assert!(apply_action(
1595            payout_state,
1596            &zero_fee_config(),
1597            None,
1598            &SELF,
1599            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1600        )
1601        .is_err());
1602    }
1603
1604    #[cfg(all(feature = "action-refresh-lifecycle", feature = "action-sync-external"))]
1605    #[kani::proof]
1606    #[kani::unwind(8)]
1607    fn refresh_lifecycle_mutates_only_external_assets_and_returns_idle() {
1608        let idle = bounded_amount();
1609        let external = bounded_amount();
1610        let synced_external = bounded_amount();
1611        let shares = bounded_amount();
1612        let op_id = 71;
1613
1614        let state =
1615            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1616        let started = apply_action(
1617            state,
1618            &zero_fee_config(),
1619            None,
1620            &SELF,
1621            KernelAction::begin_refreshing(op_id, vec![1, 2], TimestampNs::ZERO),
1622        )
1623        .unwrap()
1624        .state;
1625        assert!(started.op_state.is_refreshing());
1626        assert_eq!(started.idle_assets, idle);
1627        assert_eq!(started.external_assets, external);
1628        assert_eq!(started.total_assets, idle + external);
1629        assert_eq!(started.total_shares, shares);
1630
1631        let synced = apply_action(
1632            started,
1633            &zero_fee_config(),
1634            None,
1635            &SELF,
1636            KernelAction::sync_external_assets(synced_external, op_id, TimestampNs::ZERO),
1637        )
1638        .unwrap()
1639        .state;
1640
1641        let result = apply_action(
1642            synced,
1643            &zero_fee_config(),
1644            None,
1645            &SELF,
1646            KernelAction::finish_refreshing(op_id, TimestampNs::ZERO),
1647        )
1648        .unwrap();
1649
1650        assert!(result.state.op_state.is_idle());
1651        assert_eq!(result.state.idle_assets, idle);
1652        assert_eq!(result.state.external_assets, synced_external);
1653        assert_eq!(result.state.total_assets, idle + synced_external);
1654        assert_eq!(result.state.total_shares, shares);
1655        assert_asset_sum(&result.state);
1656    }
1657
1658    #[cfg(feature = "action-refresh-fees")]
1659    #[kani::proof]
1660    #[kani::unwind(8)]
1661    fn refresh_fees_zero_fee_rates_only_update_anchor() {
1662        let idle = bounded_amount();
1663        let external = bounded_amount();
1664        let shares = nonzero_bounded_amount();
1665        let anchor_assets = bounded_amount();
1666        let now = TimestampNs::from_nanos(1);
1667
1668        let mut state =
1669            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1670        state.fee_anchor = FeeAccrualAnchor::new(anchor_assets, TimestampNs::ZERO);
1671        let before = state.clone();
1672        let before_queue = before.withdraw_queue.status();
1673
1674        let result = apply_action(
1675            state,
1676            &zero_fee_config(),
1677            None,
1678            &SELF,
1679            KernelAction::refresh_fees(now),
1680        )
1681        .unwrap();
1682
1683        assert_eq!(result.state.idle_assets, before.idle_assets);
1684        assert_eq!(result.state.external_assets, before.external_assets);
1685        assert_eq!(result.state.total_assets, before.total_assets);
1686        assert_eq!(result.effects.len(), 1);
1687        assert_emit_event_effect(&result.effects[0]);
1688        assert_eq!(result.state.total_shares, before.total_shares);
1689        assert_eq!(
1690            result.state.fee_anchor.total_assets,
1691            result.state.total_assets
1692        );
1693        assert!(result.state.fee_anchor.timestamp_ns == now);
1694        assert!(result.state.fee_anchor.timestamp_ns > before.fee_anchor.timestamp_ns);
1695        assert!(result.state.op_state.is_idle());
1696        assert_eq!(
1697            result.state.withdraw_queue.status().length,
1698            before_queue.length
1699        );
1700        assert_eq!(
1701            result.state.withdraw_queue.status().total_escrow_shares,
1702            before_queue.total_escrow_shares
1703        );
1704        assert_eq!(
1705            result.state.withdraw_queue.status().total_expected_assets,
1706            before_queue.total_expected_assets
1707        );
1708        assert_eq!(result.state.next_op_id, before.next_op_id);
1709        assert_asset_sum(&result.state);
1710    }
1711
1712    #[cfg(feature = "action-refresh-fees")]
1713    #[kani::proof]
1714    #[kani::unwind(8)]
1715    fn refresh_fees_zero_anchor_active_rates_mint_no_shares_and_advance_checkpoint() {
1716        let idle = 100u128;
1717        let external = 0u128;
1718        let shares = 100u128;
1719        let now = TimestampNs::from_nanos(1);
1720
1721        let mut state =
1722            VaultState::with_initial(idle + external, shares, idle, external, TimestampNs::ZERO);
1723        state.fee_anchor = FeeAccrualAnchor::new(0, TimestampNs::ZERO);
1724        let before = state.clone();
1725        let before_queue = before.withdraw_queue.status();
1726
1727        let result = apply_action(
1728            state,
1729            &active_fee_config(),
1730            None,
1731            &SELF,
1732            KernelAction::refresh_fees(now),
1733        )
1734        .unwrap();
1735
1736        // A zero fee checkpoint excludes the existing balance from the
1737        // fee-accrual basis, so even active fee rates must crystallize
1738        // nothing until a legitimate checkpoint exists.
1739        assert_eq!(result.effects.len(), 1);
1740        assert_emit_event_effect(&result.effects[0]);
1741        assert_eq!(result.state.total_shares, before.total_shares);
1742        assert_eq!(result.state.idle_assets, before.idle_assets);
1743        assert_eq!(result.state.external_assets, before.external_assets);
1744        assert_eq!(result.state.total_assets, before.total_assets);
1745        assert_eq!(
1746            result.state.fee_anchor.total_assets,
1747            result.state.total_assets
1748        );
1749        assert!(result.state.fee_anchor.timestamp_ns == now);
1750        assert!(result.state.fee_anchor.timestamp_ns > before.fee_anchor.timestamp_ns);
1751        assert!(result.state.op_state.is_idle());
1752        assert_eq!(
1753            result.state.withdraw_queue.status().length,
1754            before_queue.length
1755        );
1756        assert_eq!(
1757            result.state.withdraw_queue.status().total_escrow_shares,
1758            before_queue.total_escrow_shares
1759        );
1760        assert_eq!(
1761            result.state.withdraw_queue.status().total_expected_assets,
1762            before_queue.total_expected_assets
1763        );
1764        assert_eq!(result.state.next_op_id, before.next_op_id);
1765        assert_asset_sum(&result.state);
1766    }
1767}
1768pub use types::{ActualIdx, Address, AssetId, DurationNs, ExpectedIdx, KernelVersion, TimestampNs};
1769pub use utils::TimeGate;