Fungible vaults

Fungible vaults are very similar to fungible buckets. The main differences are the following features:

1. They cannot have resources put into or taken out of them if they are frozen. Freezing and unfreezing vaults are access controlled.

2. XRD vaults in particular can be used to lock fees for transactions.

3. They support recall functionality. This is especially useful for "renting" resources to others. The special recaller role has the ability to recall resources from any vault of this type.

4. They can burn resources, deleting them from existence forever.

Below is a list of all the functions that are unique to vaults. Please see section ref↗ for the rest of the functions, as they are the same.

Method: lock_fee()

The method signature is lock_fee(amount: Decimal, contingent: bool, api: &mut Y).

This method is intended to be used only on XRD vaults. All other vaults will return an error if this method is called on them.

The method performs the same checks on the amount as the take_advanced() method does. It then ensures that the COSTING module is enabled, to ensure that fees cannot be locked when the module is disabled.

The method then goes through the same flow as take_advanced() in order to remove amount resources from this vault. Finally, it calls the Radix Engine's lock_fee() function, which handles using this fee to pay for the transaction.

More information on how the Radix Engine handles locking the fee can be found in section ref↗.

Method: recall()

The method signature is recall(amount: Decimal, api: &mut Y).

This method is used to recall resources. It can only be called by the RECALLER_ROLE. Additionally, the VaultRecall feature must be enabled when the vault is created.

Otherwise, it performs the exact same flow of actions as the take_advanced() function in order to remove resources from the vault.

Method: freeze()

The method signature is freeze(to_freeze: VaultFreezeFlags, api: &mut Y).

This method is used to freeze the vault. The to_freeze argument is of type VaultFreezeFlags:

Effectively, the FREEZER_ROLE can freeze withdrawals, deposits, or burns (and any combination of the three). Additionally, the VaultFreezable feature must be enabled when the vault is created.

Method: unfreeze()

The method signature is unfreeze(to_freeze: VaultFreezeFlags, api: &mut Y).

This method is used to unfreeze the vault. In this case, the FREEZER_ROLE can unfreeze withdrawals, deposits, or burns (and any combination of the three). Additionally, the VaultFreezable feature must be enabled when the vault is created.

Nonfungible vaults

Nonfungible vaults are very similar to nonfungible buckets. The main differences are the following features:

1. Nonfungible vaults cannot have resources put into or taken out of them if they are frozen. Freezing and unfreezing vaults are access controlled.

2. They support recall functionality. This is especially useful for "renting" resources to others. The special recaller role has the ability to recall resources from any vault of this type.

3. They can burn resources, deleting them from existence forever.

The functions that are unique to nonfungible vaults have the same behavior as the functions unique to fungible vaults:

1. Recalling, freezing, and unfreezing vaults are protected and thus can only be called by the RECALLER_ROLE and FREEZER_ROLE, respectively.

2. The VaultRecall and VaultFreezable features must be enabled to use the aforementioned features.