Buckets and Vaults

Because Scrypto is about safe resource handling, we introduce the concept of resource containers. There are two types of resource containers: Buckets and Vaults.

• Bucket - A bucket is a temporary container used to move resources during a transaction; therefore, it only exist in the duration of the transaction.

• Vault - A vault is a permanent container and at the end of each transaction, all resources must be stored in a Vault.

Buckets are transient resource containers which are used to move resources from one vault to another. As such, buckets are dropped at the end of the transaction and the resource held by the bucket must be stored in a vault or burned.

pub fn vault_to_vault(&mut self) {
  let bucket: Bucket = self.vault.take(dec!("1"));
  self.other_vault.put(bucket);
}

Fungible/NonFungible

Buckets and vaults may be further categorized to be Fungible or NonFungible adding four more types of resource containers:

• FungibleBucket - A bucket containing an amount of some fungible resource.

• NonFungibleBucket - A bucket containing an amount of some non-fungible resource.

• FungibleVault - A vault containing an amount of some fungible resource.

• NonFungibleVault - A vault containing an amount of some non-fungible resource.

These more specific types allows one to call more specialized methods for the given resource type:

pub fn display_non_fungibles(bucket: Bucket) -> Bucket {
  let non_fungible_bucket: NonFungibleBucket = bucket.as_non_fungible();
  println!("{:?}", non_fungible_bucket.non_fungibles());
  non_fungible_bucket.into()
}

Note that the above will panic if the passed in bucket is actually of fungible type.

Buckets

Buckets and it’s Fungible/NonFungible variants are the main mechanism through which assets move. Below is a table of methods available to work with buckets.

Bucket Methods

FungibleBucket Methods

A FungibleBucket inherits all of the Bucket methods with the following additional methods:

NonFungibleBucket Methods

A NonFungibleBucket inherits all of the Bucket methods with the following additional methods:

Vaults

Buckets are used to store resources while they are moving during a transaction. On the other hand, vaults are used to store resources for longer-term in-between transactions. The distinction between these two containers allows the system to make sure no resources are ever lost if, for example, someone is withdrawing tokens from their account but forgets to insert them into another vault.

The most straightforward way to illustrate the concept of vaults is with the account components. Each account component contains a vault for each resource type it owns, as seen in its state definition:

struct Account {
  vaults: KeyValueStore<ResourceAddress, Vault>
}

When an account receives a new token (e.g. through a call to one of its deposit methods), it checks if it already instantiated a vault of this particular resource type. If a vault for the received resource type does not exist, one is created and the received tokens are stored in it.

You can visualize the vaults and resources present on an account component (or any component) by using the resim show <component_address> command as shown below.

> resim new-account
> resim new-token-fixed --symbol BTC --name Bitcoin 21000000
> resim show [account_address]

Component: account_sim1q0esun0yw3y6h4glaea4fds5kzd3j0hayqxpec589m3s0kjz2g
Access Rules
State: Tuple(KeyValueStore("b825ef8e0e15fe71d85b7e3f4adb4c0c8bb9e9902fdb52ff4d7c73219c7d286403040000"))
Key Value Store: AccountComponent[03f30e4de47449abd51fee7b54b614b09b193efd200c1ce2872ee3][...]
├─ ResourceAddress("resource_sim1qzkcyv5dwq3r6kawy6pxpvcythx8rh8ntum6ws62p95sqjjpwr") => Vault("b825ef8e0e15fe71d85b7e3f4adb4c0c8bb9e9902fdb52ff4d7c73219c7d286405040000")
└─ ResourceAddress("resource_sim1qrgs0ge3nm2sh6fc09rtfgzcx4jfvk6uk77t9sqdu66qrs6z50") => Vault("93a0a362a5aa37e847e5b9a94343061ee6738f19ad81f5ce04b4558cd6fbd2f705040000")
Resources:
├─ { amount: 1000, resource address: resource_sim1qzkcyv5dwq3r6kawy6pxpvcythx8rh8ntum6ws62p95sqjjpwr, name: "Radix", symbol: "XRD" }
└─ { amount: 21000000, resource address: resource_sim1qrgs0ge3nm2sh6fc09rtfgzcx4jfvk6uk77t9sqdu66qrs6z50, name: "Bitcoin", symbol: "BTC" }

In the Key Value Store section, you can see the mapping between the resource addresses and their corresponding Vault. Resim then displays the resource list in a user-friendly format in the Resources section.

Creating Vaults

In Scrypto, there are two main ways for creating a Vault:

Here is a simple example:

use scrypto::prelude::*;

#[blueprint]
mod my_module {
    struct MyBlueprint {
        my_vault: Vault
    }

    impl MyBlueprint {
        pub fn instantiate(tokens: Bucket) -> Global<MyBlueprint> {
            Self {
                // Create a Vault from the provided bucket
                // and store in on the component state
                my_vault: Vault::with_bucket(tokens)
            }.instantiate().globalize()
        }
    }
}

Just like buckets have to be deposited into a vault by the end of a transaction, Vaults must be stored on a component state by the end of a transaction.

Vault Methods

FungibleVault Methods

A FungibleVault inherits all of the Vault methods with the following additional methods:

NonFungibleVault Methods

A NonFungibleVault inherits all of the Vault methods with the following additional methods: