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 pub(crate) fn initialize_storage_management() -> u64 {
45 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 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 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 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 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 #[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 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 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}