templar_registry_contract/
storage_management.rs

1use near_sdk::{assert_one_yocto, env, near, require, AccountId, AccountIdRef, NearToken, Promise};
2use near_sdk_contract_tools::{
3    hook::Hook,
4    owner::OwnerInternal,
5    slot::Slot,
6    standard::nep145::{
7        Nep145Controller, Nep145ControllerInternal, Nep145ForceUnregister, StorageBalance,
8        StorageBalanceBounds,
9    },
10};
11use templar_common::UnwrapReject;
12
13#[cfg(test)]
14mod solvency_tests;
15
16use crate::{state::StorageKey, Contract, ContractExt};
17
18impl Nep145ControllerInternal for Contract {
19    type ForceUnregisterHook = Self;
20
21    fn slot_account(account_id: &AccountIdRef) -> Slot<StorageBalance> {
22        Slot::new(StorageKey::StorageAccount {
23            hash: env::sha256_array(account_id.as_bytes()),
24        })
25    }
26
27    fn slot_balance_bounds() -> Slot<StorageBalanceBounds> {
28        Slot::new(StorageKey::StorageBounds)
29    }
30}
31
32impl Hook<Contract, Nep145ForceUnregister<'_>> for Contract {
33    fn hook<R>(
34        _contract: &mut Contract,
35        _action: &Nep145ForceUnregister<'_>,
36        _f: impl FnOnce(&mut Contract) -> R,
37    ) -> R {
38        env::panic_str("Forced storage unregistration is not supported")
39    }
40}
41
42impl Contract {
43    /// Called only when initializing a fresh ledger, including the V1 migration.
44    pub(crate) fn initialize_storage_management() -> u64 {
45        // Hashed account keys and fixed-width balances make this minimum independent
46        // of the account name. The bounds record itself is registry-funded.
47        let mut account: Slot<StorageBalance> =
48            Slot::new(StorageKey::StorageAccount { hash: [0; 32] });
49        require!(!account.exists(), "Storage measurement slot is occupied");
50        let before = env::storage_usage();
51        account.write(&StorageBalance::default());
52        let bytes = env::storage_usage()
53            .checked_sub(before)
54            .expect_or_reject("Invariant violation: storage registration did not grow storage");
55        account.remove();
56        let min = env::storage_byte_cost()
57            .checked_mul(u128::from(bytes))
58            .expect_or_reject("Storage registration cost overflow");
59        <Self as Nep145ControllerInternal>::slot_balance_bounds()
60            .write(&StorageBalanceBounds { min, max: None });
61        let key_bytes = u64::try_from(account.key.len()).unwrap_or_reject();
62        let balance_bytes = u64::try_from(
63            near_sdk::borsh::object_length(&StorageBalance::default()).unwrap_or_reject(),
64        )
65        .unwrap_or_reject();
66        bytes
67            .checked_sub(key_bytes)
68            .and_then(|bytes| bytes.checked_sub(balance_bytes))
69            .expect_or_reject("Invariant violation: storage entry overhead")
70    }
71
72    /// Lock a registered payer's available balance for retained registry data.
73    pub(crate) fn charge_storage(&mut self, account_id: &AccountId, amount: NearToken) {
74        self.lock_storage(account_id, amount)
75            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
76        let available = self
77            .available_storage_balance
78            .checked_sub(amount)
79            .expect_or_reject("Invariant violation: aggregate storage balance underflow");
80        self.available_storage_balance = available;
81    }
82
83    /// Credit freed data to its original payer without unlocking registration.
84    pub(crate) fn release_storage(&mut self, account_id: &AccountId, amount: NearToken) {
85        let balance = self
86            .get_storage_balance(account_id)
87            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
88        let releasable = balance
89            .total
90            .checked_sub(balance.available)
91            .and_then(|locked| locked.checked_sub(self.get_storage_balance_bounds().min))
92            .expect_or_reject("Invariant violation: registration storage is not locked");
93        require!(
94            amount <= releasable,
95            "Cannot release registration storage balance"
96        );
97        let available = self
98            .available_storage_balance
99            .checked_add(amount)
100            .expect_or_reject("Aggregate storage balance overflow");
101        self.unlock_storage(account_id, amount)
102            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
103        self.available_storage_balance = available;
104    }
105
106    /// Reserve still-unallocated owner/proposed-owner capacity without replacing Owner's derive.
107    fn owner_storage_reserve(&self) -> NearToken {
108        let maximum_value_bytes =
109            u64::try_from(std::mem::size_of::<u32>() + AccountId::MAX_LEN).unwrap_or_reject();
110        let bytes = [Self::slot_owner(), Self::slot_proposed_owner()]
111            .into_iter()
112            .map(|slot| match env::storage_read(&slot.key) {
113                Some(value) => maximum_value_bytes
114                    .checked_sub(u64::try_from(value.len()).unwrap_or_reject())
115                    .expect_or_reject("Invariant violation: oversized ownership slot"),
116                None => {
117                    u64::try_from(slot.key.len()).unwrap_or_reject()
118                        + maximum_value_bytes
119                        + self.storage_entry_overhead
120                }
121            })
122            .sum::<u64>();
123        env::storage_byte_cost()
124            .checked_mul(u128::from(bytes))
125            .expect_or_reject("Owner storage reserve overflow")
126    }
127
128    /// Registry-funded writes and transfers must not spend user storage credits.
129    pub(crate) fn assert_storage_solvency(&self, outgoing: NearToken) {
130        let required = env::storage_byte_cost()
131            .checked_mul(u128::from(env::storage_usage()))
132            .and_then(|storage| storage.checked_add(self.available_storage_balance))
133            .and_then(|storage| storage.checked_add(self.pending_deployment_storage))
134            .and_then(|storage| storage.checked_add(self.owner_storage_reserve()))
135            .expect_or_reject("Storage liability overflow");
136        let remaining = env::account_balance()
137            .checked_sub(outgoing)
138            .expect_or_reject("Insufficient registry balance for transfer");
139        require!(
140            remaining >= required,
141            "Insufficient registry balance to cover storage liabilities"
142        );
143    }
144}
145
146#[near]
147impl Contract {
148    /// Register or fund an account. Refunds always go to the depositing predecessor.
149    #[payable]
150    pub fn storage_deposit(
151        &mut self,
152        account_id: Option<AccountId>,
153        registration_only: Option<bool>,
154    ) -> StorageBalance {
155        let predecessor = env::predecessor_account_id();
156        let account_id = account_id.unwrap_or_else(|| predecessor.clone());
157        let deposit = env::attached_deposit();
158        let existing = self.get_storage_balance(&account_id).ok();
159        let registration_only = registration_only.unwrap_or(false);
160        if let Some(balance) = existing.as_ref().filter(|_| registration_only) {
161            self.assert_storage_solvency(deposit);
162            if !deposit.is_zero() {
163                Promise::new(predecessor).transfer(deposit).detach();
164            }
165            return balance.clone();
166        }
167
168        let minimum = self.get_storage_balance_bounds().min;
169        let credited = if registration_only { minimum } else { deposit };
170        require!(deposit >= credited, "Insufficient storage deposit");
171        let available_increase = if existing.is_none() {
172            credited
173                .checked_sub(minimum)
174                .expect_or_reject("Insufficient storage deposit")
175        } else {
176            credited
177        };
178        let aggregate = self
179            .available_storage_balance
180            .checked_add(available_increase)
181            .expect_or_reject("Aggregate storage balance overflow");
182        let mut balance = self
183            .deposit_to_storage_account(&account_id, credited)
184            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
185        if existing.is_none() {
186            balance = self
187                .lock_storage(&account_id, minimum)
188                .unwrap_or_else(|error| env::panic_str(&error.to_string()));
189        }
190        self.available_storage_balance = aggregate;
191        let refund = deposit
192            .checked_sub(credited)
193            .expect_or_reject("Storage refund underflow");
194        self.assert_storage_solvency(refund);
195        if !refund.is_zero() {
196            Promise::new(predecessor).transfer(refund).detach();
197        }
198        balance
199    }
200
201    #[payable]
202    pub fn storage_withdraw(&mut self, amount: Option<NearToken>) -> StorageBalance {
203        assert_one_yocto();
204        let account_id = env::predecessor_account_id();
205        let balance = self
206            .get_storage_balance(&account_id)
207            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
208        let amount = amount.unwrap_or(balance.available);
209        require!(
210            amount <= balance.available,
211            "Insufficient available storage balance"
212        );
213        let aggregate = self
214            .available_storage_balance
215            .checked_sub(amount)
216            .expect_or_reject("Invariant violation: aggregate storage balance underflow");
217        let balance = self
218            .withdraw_from_storage_account(&account_id, amount)
219            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
220        self.available_storage_balance = aggregate;
221        self.assert_storage_solvency(amount);
222        if !amount.is_zero() {
223            Promise::new(account_id).transfer(amount).detach();
224        }
225        balance
226    }
227
228    #[payable]
229    pub fn storage_unregister(&mut self, force: Option<bool>) -> bool {
230        assert_one_yocto();
231        let account_id = env::predecessor_account_id();
232        let Ok(balance) = self.get_storage_balance(&account_id) else {
233            return false;
234        };
235        if force.unwrap_or(false) {
236            // The hook deliberately rejects even accounts without retained code.
237            self.force_unregister_storage_account(&account_id)
238                .unwrap_or_else(|error| env::panic_str(&error.to_string()));
239            unreachable!("Force unregistration hook must reject")
240        }
241        let minimum = self.get_storage_balance_bounds().min;
242        let locked = balance
243            .total
244            .checked_sub(balance.available)
245            .expect_or_reject("Invariant violation: available storage exceeds total");
246        require!(
247            locked == minimum,
248            "Cannot unregister with locked storage balance"
249        );
250        let aggregate = self
251            .available_storage_balance
252            .checked_sub(balance.available)
253            .expect_or_reject("Invariant violation: aggregate storage balance underflow");
254        // The controller requires *zero* locked balance to unregister. Release
255        // only the verified registration reserve immediately before removing it.
256        self.unlock_storage(&account_id, minimum)
257            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
258        let refund = self
259            .unregister_storage_account(&account_id)
260            .unwrap_or_else(|error| env::panic_str(&error.to_string()));
261        self.available_storage_balance = aggregate;
262        self.assert_storage_solvency(refund);
263        Promise::new(account_id).transfer(refund).detach();
264        true
265    }
266
267    pub fn storage_balance_of(&self, account_id: AccountId) -> Option<StorageBalance> {
268        self.get_storage_balance(&account_id).ok()
269    }
270
271    pub fn storage_balance_bounds(&self) -> StorageBalanceBounds {
272        self.get_storage_balance_bounds()
273    }
274}
275
276#[cfg(test)]
277mod tests {
278    use near_sdk::{
279        mock::MockAction,
280        test_utils::{get_created_receipts, VMContextBuilder},
281        testing_env,
282    };
283    use rstest::rstest;
284
285    use super::*;
286
287    fn account(name: &str) -> AccountId {
288        name.parse().unwrap()
289    }
290
291    fn tokens(amount: u128) -> NearToken {
292        NearToken::from_yoctonear(amount)
293    }
294
295    fn context(predecessor: &str, deposit: NearToken) {
296        testing_env!(VMContextBuilder::new()
297            .predecessor_account_id(account(predecessor))
298            .attached_deposit(deposit)
299            .account_balance(NearToken::from_near(100))
300            .storage_usage(env::storage_usage())
301            .build());
302    }
303
304    fn setup() -> Contract {
305        testing_env!(VMContextBuilder::new()
306            .predecessor_account_id(account("owner.near"))
307            .account_balance(NearToken::from_near(100))
308            .build());
309        Contract::new()
310    }
311
312    fn register(contract: &mut Contract, name: &str, extra: NearToken) -> StorageBalance {
313        let deposit = contract
314            .storage_balance_bounds()
315            .min
316            .checked_add(extra)
317            .unwrap();
318        context(name, deposit);
319        contract.storage_deposit(None, None)
320    }
321
322    fn transfers() -> Vec<(AccountId, NearToken)> {
323        get_created_receipts()
324            .into_iter()
325            .flat_map(|receipt| {
326                receipt
327                    .actions
328                    .into_iter()
329                    .filter_map(move |action| match action {
330                        MockAction::Transfer { deposit, .. } => {
331                            Some((receipt.receiver_id.clone(), deposit))
332                        }
333                        _ => None,
334                    })
335            })
336            .collect()
337    }
338
339    fn assert_panics(expected: &str, f: impl FnOnce()) {
340        let panic = std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)).unwrap_err();
341        let actual = panic
342            .downcast_ref::<String>()
343            .map(String::as_str)
344            .or_else(|| panic.downcast_ref::<&str>().copied())
345            .unwrap();
346        assert!(
347            actual.contains(expected),
348            "expected {expected:?}, got {actual:?}"
349        );
350    }
351
352    #[test]
353    fn minimum_exactly_covers_fixed_size_registration() {
354        let mut contract = setup();
355        let bounds = contract.storage_balance_bounds();
356        assert!(bounds.min > NearToken::ZERO);
357        assert_eq!(bounds.max, None);
358        let before = env::storage_usage();
359        let balance = register(&mut contract, "alice.near", NearToken::ZERO);
360        let bytes = env::storage_usage().checked_sub(before).unwrap();
361        assert_eq!(
362            bounds.min,
363            env::storage_byte_cost()
364                .checked_mul(u128::from(bytes))
365                .unwrap()
366        );
367        assert_eq!(
368            balance,
369            StorageBalance {
370                total: bounds.min,
371                available: NearToken::ZERO
372            }
373        );
374        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
375        assert!(transfers().is_empty());
376        let before = env::storage_usage();
377        register(
378            &mut contract,
379            "a-much-longer-account-name.near",
380            NearToken::ZERO,
381        );
382        assert_eq!(env::storage_usage() - before, bytes);
383    }
384
385    #[test]
386    fn third_party_registration_only_refunds_payer_and_preserves_target() {
387        let mut contract = setup();
388        let minimum = contract.storage_balance_bounds().min;
389        context("sponsor.near", minimum.checked_add(tokens(17)).unwrap());
390        let balance = contract.storage_deposit(Some(account("alice.near")), Some(true));
391        assert_eq!(balance.total, minimum);
392        assert_eq!(balance.available, NearToken::ZERO);
393        assert_eq!(transfers(), vec![(account("sponsor.near"), tokens(17))]);
394        assert_eq!(contract.storage_balance_of(account("sponsor.near")), None);
395        assert_eq!(
396            contract.storage_balance_of(account("alice.near")),
397            Some(balance.clone())
398        );
399        context("sponsor.near", tokens(9));
400        assert_eq!(
401            contract.storage_deposit(Some(account("alice.near")), Some(true)),
402            balance
403        );
404        assert_eq!(transfers(), vec![(account("sponsor.near"), tokens(9))]);
405        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
406    }
407
408    #[test]
409    fn deposits_and_lock_release_track_every_accounts_available_balance() {
410        let mut contract = setup();
411        let alice = account("alice.near");
412        let minimum = contract.storage_balance_bounds().min;
413        register(&mut contract, "alice.near", tokens(100));
414        register(&mut contract, "bob.near", tokens(40));
415        context("sponsor.near", tokens(20));
416        let balance = contract.storage_deposit(Some(alice.clone()), None);
417        assert_eq!(balance.total, minimum.checked_add(tokens(120)).unwrap());
418        assert_eq!(balance.available, tokens(120));
419        assert_eq!(contract.available_storage_balance, tokens(160));
420        contract.charge_storage(&alice, tokens(50));
421        assert_eq!(
422            contract
423                .storage_balance_of(alice.clone())
424                .unwrap()
425                .available,
426            tokens(70)
427        );
428        assert_eq!(contract.available_storage_balance, tokens(110));
429        contract.release_storage(&alice, tokens(30));
430        assert_eq!(
431            contract
432                .storage_balance_of(alice.clone())
433                .unwrap()
434                .available,
435            tokens(100)
436        );
437        assert_eq!(contract.available_storage_balance, tokens(140));
438        assert_panics("Cannot release registration", || {
439            contract.release_storage(&alice, tokens(21));
440        });
441        assert_eq!(
442            contract.storage_balance_of(alice).unwrap().available,
443            tokens(100)
444        );
445        assert_eq!(contract.available_storage_balance, tokens(140));
446    }
447
448    #[test]
449    fn withdrawals_support_partial_all_zero_and_reject_excess() {
450        let mut contract = setup();
451        let minimum = contract.storage_balance_bounds().min;
452        register(&mut contract, "alice.near", tokens(100));
453        context("alice.near", tokens(1));
454        let balance = contract.storage_withdraw(Some(tokens(30)));
455        assert_eq!(balance.total, minimum.checked_add(tokens(70)).unwrap());
456        assert_eq!(balance.available, tokens(70));
457        assert_eq!(contract.available_storage_balance, tokens(70));
458        assert_eq!(transfers(), vec![(account("alice.near"), tokens(30))]);
459        context("alice.near", tokens(1));
460        assert_panics("Insufficient available", || {
461            contract.storage_withdraw(Some(tokens(71)));
462        });
463        assert_eq!(contract.available_storage_balance, tokens(70));
464        context("alice.near", tokens(1));
465        assert_eq!(
466            contract.storage_withdraw(None),
467            StorageBalance {
468                total: minimum,
469                available: NearToken::ZERO
470            }
471        );
472        assert_eq!(transfers(), vec![(account("alice.near"), tokens(70))]);
473        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
474        context("alice.near", tokens(1));
475        assert_eq!(contract.storage_withdraw(None).available, NearToken::ZERO);
476        assert!(transfers().is_empty());
477    }
478
479    #[test]
480    fn unregister_requires_release_and_refunds_total_without_other_users_credit() {
481        let mut contract = setup();
482        let alice = account("alice.near");
483        let minimum = contract.storage_balance_bounds().min;
484        register(&mut contract, "alice.near", tokens(100));
485        register(&mut contract, "bob.near", tokens(20));
486        contract.charge_storage(&alice, tokens(60));
487        context("alice.near", tokens(1));
488        assert_panics("Cannot unregister with locked", || {
489            contract.storage_unregister(None);
490        });
491        assert_eq!(contract.available_storage_balance, tokens(60));
492        assert!(contract.storage_balance_of(alice.clone()).is_some());
493        contract.release_storage(&alice, tokens(60));
494        context("alice.near", tokens(1));
495        assert!(contract.storage_unregister(Some(false)));
496        assert_eq!(contract.storage_balance_of(alice), None);
497        assert_eq!(contract.available_storage_balance, tokens(20));
498        assert_eq!(
499            transfers(),
500            vec![(
501                account("alice.near"),
502                minimum.checked_add(tokens(100)).unwrap()
503            )]
504        );
505        context("alice.near", tokens(1));
506        assert!(!contract.storage_unregister(None));
507        assert!(transfers().is_empty());
508    }
509
510    #[test]
511    fn unregister_minimum_only_releases_registration_reserve() {
512        let mut contract = setup();
513        let minimum = contract.storage_balance_bounds().min;
514        register(&mut contract, "alice.near", NearToken::ZERO);
515        context("alice.near", tokens(1));
516        assert!(contract.storage_unregister(None));
517        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
518        assert_eq!(transfers(), vec![(account("alice.near"), minimum)]);
519    }
520
521    #[test]
522    fn force_rejects_registered_accounts_and_does_not_erase_their_balance() {
523        let mut contract = setup();
524        let balance = register(&mut contract, "alice.near", tokens(100));
525        context("alice.near", tokens(1));
526        assert_panics("Forced storage unregistration is not supported", || {
527            contract.storage_unregister(Some(true));
528        });
529        assert_eq!(
530            contract.storage_balance_of(account("alice.near")),
531            Some(balance)
532        );
533        assert_eq!(contract.available_storage_balance, tokens(100));
534        context("absent.near", tokens(1));
535        assert!(!contract.storage_unregister(Some(true)));
536        assert!(transfers().is_empty());
537    }
538
539    #[test]
540    fn registration_underpayment_and_unregistered_operations_fail() {
541        let mut contract = setup();
542        let minimum = contract.storage_balance_bounds().min;
543        context("alice.near", minimum.checked_sub(tokens(1)).unwrap());
544        assert_panics("Insufficient storage deposit", || {
545            contract.storage_deposit(None, None);
546        });
547        assert_eq!(contract.storage_balance_of(account("alice.near")), None);
548        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
549        context("alice.near", tokens(1));
550        assert_panics("is not registered", || {
551            contract.storage_withdraw(None);
552        });
553        assert_panics("is not registered", || {
554            contract.release_storage(&account("alice.near"), tokens(1));
555        });
556    }
557
558    #[test]
559    fn charge_rejects_unregistered_or_underfunded_payers_without_changing_ledger() {
560        let mut contract = setup();
561        let alice = account("alice.near");
562        assert_panics("is not registered", || {
563            contract.charge_storage(&alice, tokens(1));
564        });
565        assert_eq!(contract.available_storage_balance, NearToken::ZERO);
566        let balance = register(&mut contract, "alice.near", tokens(10));
567        assert_panics("insufficient balance", || {
568            contract.charge_storage(&alice, tokens(11));
569        });
570        assert_eq!(
571            contract.storage_balance_of(alice.clone()),
572            Some(balance.clone())
573        );
574        assert_eq!(contract.available_storage_balance, tokens(10));
575        contract.charge_storage(&alice, NearToken::ZERO);
576        contract.release_storage(&alice, NearToken::ZERO);
577        assert_eq!(contract.storage_balance_of(alice), Some(balance));
578        assert_eq!(contract.available_storage_balance, tokens(10));
579    }
580
581    #[test]
582    fn storage_views_keep_standard_json_amounts_and_absence() {
583        let mut contract = setup();
584        assert_eq!(contract.storage_balance_of(account("absent.near")), None);
585        let bounds = contract.storage_balance_bounds();
586        assert_eq!(
587            near_sdk::serde_json::to_value(&bounds).unwrap(),
588            near_sdk::serde_json::json!({ "min": bounds.min.as_yoctonear().to_string(), "max": null }),
589        );
590        let balance = register(&mut contract, "alice.near", tokens(10));
591        assert_eq!(
592            near_sdk::serde_json::to_value(balance).unwrap(),
593            near_sdk::serde_json::json!({
594                "total": bounds.min.checked_add(tokens(10)).unwrap().as_yoctonear().to_string(),
595                "available": "10",
596            }),
597        );
598    }
599
600    #[rstest]
601    fn withdrawal_and_unregistration_require_one_yocto(
602        #[values(0, 2)] deposit: u128,
603        #[values(false, true)] unregister: bool,
604    ) {
605        let mut contract = setup();
606        register(&mut contract, "alice.near", tokens(100));
607        context("alice.near", tokens(deposit));
608        assert_panics("Requires attached deposit of exactly 1 yoctoNEAR", || {
609            if unregister {
610                contract.storage_unregister(None);
611            } else {
612                contract.storage_withdraw(None);
613            }
614        });
615        assert_eq!(contract.available_storage_balance, tokens(100));
616    }
617
618    #[test]
619    fn solvency_protects_storage_and_unwithdrawn_credits() {
620        let mut contract = setup();
621        register(&mut contract, "alice.near", tokens(100));
622        let required = env::storage_byte_cost()
623            .checked_mul(u128::from(env::storage_usage()))
624            .unwrap()
625            .checked_add(tokens(100))
626            .unwrap()
627            .checked_add(contract.owner_storage_reserve())
628            .unwrap();
629        testing_env!(VMContextBuilder::new()
630            .account_balance(required.checked_add(tokens(10)).unwrap())
631            .storage_usage(env::storage_usage())
632            .build());
633        contract.assert_storage_solvency(tokens(10));
634        assert_panics(
635            "Insufficient registry balance to cover storage liabilities",
636            || {
637                contract.assert_storage_solvency(tokens(11));
638            },
639        );
640    }
641}