10. Composable Resources

In this tutorial, we're going to walk through how resources can own other resources by creating, deploying, and moving composable NFTs.

---

tip

Open the starter code for this tutorial in the Flow Playground:

https://play.onflow.org/01f812d7-799a-42fd-b9cb-9ffe556e02ad

The tutorial will be asking you do take various actions to interact with this code.

Action

The code in this tutorial and in the playground uses Cadence 0.42. The link will still work with the current version of the playground, but when the playground is updated to Cadence 1.0, the link will be replaced with a 1.0-compatible version. It is recommended that since Flow is so close to upgrading to Cadence 1.0, that you learn Cadence 1.0 features and syntax.

Action

Instructions that require you to take action are always included in a callout box like this one. These highlighted actions are all that you need to do to get your code running, but reading the rest is necessary to understand the language's design.

Resources owning other resources is a powerful feature in the world of blockchain and smart contracts. To showcase how this feature works on Flow, this tutorial will take you through these steps with a composable NFT:

1. Deploy the Kitty and KittyHat definitions to account 0x01
2. Create a Kitty and two KittyHats and store them in your account
3. Move the Kitties and Hats around to see how composable NFTs function on Flow

Before proceeding with this tutorial, we recommend following the instructions in Getting Started and Hello, World! to learn about the Playground and Cadence.

Resources Owning Resources

---

The NFT collections talked about in Non-Fungible Tokens are examples of resources that own other resources. We have a resource, the NFT collection, that has ownership of the NFT resources that are stored within it. The owner and anyone with a reference can move these resources around, but they still belong to the collection while they are in it and the code defined in the collection has ultimate control over the resources.

When the collection is moved or destroyed, all of the NFTs inside of it are moved or destroyed with it.

If the owner of the collection transferred the whole collection resource to another user's account, all of the tokens will move to the other user's account with it. The tokens don't stay in the original owner's account. This is like handing someone your wallet instead of just a dollar bill. It isn't a common action, but certainly is possible.

References cannot be created for resources that are stored in other resources. The owning resource has control over it and therefore controls the type of access that external calls have on the stored resource.

Resources Owning Resources: An Example

---

The NFT collection is a simple example of how resources can own other resources, but innovative and more powerful versions can be made.

An important feature of CryptoKitties (and other applications on the Ethereum blockchain) is that any developer can make new experiences around the existing application. Even though the original contract didn't include specific support for CryptoKitty accessories (like hats), an independent developer was still able to make hats that Kitties from the original contract could use.

Here is a basic example of how we can replicate this feature in Cadence:

Action

1. Open Contract 1, the KittyVerse.cdc contract
   
2. In the bottom right deployment modal, press the arrow to expand and make sure account 0x01 is selected as the signer.
   
3. Click the Deploy button to deploy the contract to account 0x01

The deployed contract should have the following contents:

KittyVerse.cdc

_93

// KittyVerse.cdc

_93

//

_93

// The KittyVerse contract defines two types of NFTs.

_93

// One is a KittyHat, which represents a special hat, and

_93

// the second is the Kitty resource, which can own Kitty Hats.

_93

//

_93

// You can put the hats on the cats and then call a hat function

_93

// that tips the hat and prints a fun message.

_93

//

_93

// This is a simple example of how Cadence supports

_93

// extensibility for smart contracts, but the language will soon

_93

// support even more powerful versions of this.

_93

//

_93

_93

access(all)

_93

contract KittyVerse {

_93

_93

// KittyHat is a special resource type that represents a hat

_93

access(all)

_93

resource KittyHat {

_93

_93

access(all)

_93

let id: Int

_93

_93

access(all)

_93

let name: String

_93

_93

init(id: Int, name: String) {

_93

self.id = id

_93

self.name = name

_93

}

_93

_93

// An example of a function someone might put in their hat resource

_93

access(all)

_93

fun tipHat(): String {

_93

if self.name == "Cowboy Hat" {

_93

return "Howdy Y'all"

_93

} else if self.name == "Top Hat" {

_93

return "Greetings, fellow aristocats!"

_93

}

_93

_93

return "Hello"

_93

}

_93

}

_93

_93

// Create a new hat

_93

access(all)

_93

fun createHat(id: Int, name: String): @KittyHat {

_93

return <-create KittyHat(id: id, name: name)

_93

}

_93

_93

access(all)

_93

resource Kitty {

_93

_93

access(all)

_93

let id: Int

_93

_93

// place where the Kitty hats are stored

_93

access(all)

_93

var items: @{String: KittyHat}

_93

_93

init(newID: Int) {

_93

self.id = newID

_93

self.items <- {}

_93

}

_93

_93

access(all)

_93

fun getKittyItems(): @{String: KittyHat} {

_93

var other: @{String:KittyHat} <- {}

_93

self.items <-> other

_93

return <- other

_93

}

_93

_93

access(all)

_93

fun setKittyItems(items: @{String: KittyHat}) {

_93

var other <- items

_93

self.items <-> other

_93

destroy other

_93

}

_93

_93

access(all)

_93

fun removeKittyItem(key: String): @KittyHat? {

_93

var removed <- self.items.remove(key: key)

_93

return <- removed

_93

}

_93

}

_93

_93

access(all)

_93

fun createKitty(): @Kitty {

_93

return <-create Kitty(newID: 1)

_93

}

_93

_93

}

These definitions show how a Kitty resource could own hats.

The hats are stored in a variable in the Kitty resource.

_10

// place where the Kitty hats are stored

_10

access(all)

_10

var items: <-{String: KittyHat}

A Kitty owner can take the hats off the Kitty and transfer them individually. Or the owner can transfer a Kitty that owns a hat, and the hat will go along with the Kitty.

Here is a transaction to create a Kitty and a KittyHat, store the hat in the Kitty, then store it in your account storage.

1. Open Transaction1.cdc.
2. Select account 0x01 as the only signer.
3. Send the transaction by clicking the Send button.

The transaction you sent just executed the following code:

Transaction1.cdc

_30

import KittyVerse from 0x01

_30

_30

// This transaction creates a new kitty, creates two new hats and

_30

// puts the hats on the cat. Then it stores the kitty in account storage.

_30

transaction {

_30

prepare(acct: AuthAccount) {

_30

_30

// Create the Kitty object

_30

let kitty <- KittyVerse.createKitty()

_30

_30

// Create the KittyHat objects

_30

let hat1 <- KittyVerse.createHat(id: 1, name: "Cowboy Hat")

_30

let hat2 <- KittyVerse.createHat(id: 2, name: "Top Hat")

_30

_30

let kittyItems <- kitty.getKittyItems()

_30

_30

// Put the hat on the cat!

_30

let oldCowboyHat <- kittyItems["Cowboy Hat"] <- hat1

_30

destroy oldCowboyHat

_30

let oldTopHat <- kittyItems["Top Hat"] <- hat2

_30

destroy oldTopHat

_30

_30

kitty.setKittyItems(items: <-kittyItems)

_30

_30

log("The cat has the hats")

_30

_30

// Store the Kitty in storage

_30

acct.storage.save(<-kitty, to: /storage/kitty)

_30

}

_30

}

You should see an output that looks something like this:

_10

> "The Cat has the Hats"

Now we can run a transaction to move the Kitty along with its hat, remove the cowboy hat from the Kitty, then make the Kitty tip its hat.

Action

1. Open Transaction2.cdc.
   
2. Select account 0x01 as the only signer.
   
3. Send the transaction.

In this transaction, we executed the following code:

Transaction2.cdc

_27

import KittyVerse from 0x01

_27

_27

// This transaction moves a kitty out of storage, takes the cowboy hat off of the kitty,

_27

// calls its tip hat function, and then moves it back into storage.

_27

transaction {

_27

prepare(acct: AuthAccount) {

_27

_27

// Move the Kitty out of storage, which also moves its hat along with it

_27

let kitty <- acct.storage.load<@KittyVerse.Kitty>(from: /storage/kitty)

_27

?? panic("Kitty doesn't exist!")

_27

_27

// Take the cowboy hat off the Kitty

_27

let cowboyHat <- kitty.removeKittyItem(key: "Cowboy Hat")

_27

?? panic("cowboy hat doesn't exist!")

_27

_27

// Tip the cowboy hat

_27

log(cowboyHat.tipHat())

_27

destroy cowboyHat

_27

_27

// Tip the top hat that is on the Kitty

_27

log(kitty.items["Top Hat"]?.tipHat())

_27

_27

// Move the Kitty to storage, which

_27

// also moves its hat along with it.

_27

acct.storage.save(<-kitty, to: /storage/kitty)

_27

}

_27

}

You should see something like this output:

_10

> "Howdy Y'all"

_10

> "Greetings, fellow aristocats!"

Whenever the Kitty is moved, its hats are implicitly moved along with it. This is because the hats are owned by the Kitty.

The Future is Meow! Extensibility is coming!

---

The above is a simple example of composable resources. We had to explicitly say that a Kitty could own a Hat in this example, but in the near future, Cadence will support more powerful ways of achieving resource extensibility where developers can declare types that separate resources can own even if the owning resource never specified the ownership possibility in the first place. This is a very complex problem to solve in a safe way, and the Flow community is working very hard to design a solution for this, but it is coming.

Practice what you're learned in the Flow Playground!