Top-Down and Bottom-Up Composables, What’s the Difference and Which One Should You Use?

A composable is a non-fungible token (or unique digital asset) that can own or be owned by other non-fungible tokens. Composables can be composed into aggregate structures linked by ownership.

The ERC998 standard is about two different approaches of composable tokens. The two different kinds of composables are top-down composables and bottom-up composables.

Both kinds of composables implement the ERC721 standard (so are ERC721 tokens) and extend that standard to enable them to own or be owned by other ERC721 tokens. It also provides a way for ERC721 tokens to possess/own ERC20 tokens.

You can imagine a composable that owns 20 ERC721 tokens, or a composable that owns a composable that owns a composable; or any ownership tree of composables and ERC721 tokens.

There are two different approaches (top-down and bottom-up) because they have different advantages and disadvantages. This blog post outlines advantages and disadvantages of both so you can understand the difference between them. I hope this article can help you decide which kind of composable to use for what you want to do.

Top-Down Composables

A top-down composable stores information about its child tokens. Any ERC721 token can be transferred into a top-down composable. Top-down composables are “welcoming” like a house or container. You put ERC721 tokens in them. And you can of course transfer ERC721 tokens out of them. Top-down composables are themselves ERC721 tokens so you can transfer them around just like you do regular ERC721 tokens. Imagine filling a container with a bunch of individual items and then giving the container to someone else. That’s like adding ERC721 tokens to a top-down composable and then transferring the composable to someone else.

Top-Down Advantages:

1. Any ERC721 token can be transferred to a top-down composable. Another way to say this is that any ERC721 token can be a child of a top-down composable.
2. Keeps track of child tokens nicely so if the composable contract implements enumeration then you can query and get all the child contracts and child tokenIds of a top-down composable.

Top-Down Disadvantages:

1. A top-down composable cannot be a child of a regular ERC721 token. Another way to say this is that the ownership of a top-down composable cannot be transferred to a regular ERC721 token. Another way to say this is that a regular ERC721 token cannot own a top-down composable. I say “regular ERC721” token because a top-down composable can be the child of another top-down composable. It just can’t be the child of an ERC721 token that does not have composable functionality.
2. Owner/approved-authenticated methods cannot be directly called in regular ERC721 child contracts. For example you can’t directly call the “safeTransferFrom” function in the child contract for a child token. This won’t work because the function will check if you are the immediate owner of the child token and will fail because the top-down composable is the immediate owner of the child token, not you. So instead of directly calling an authenticated method in the child contract you need to call a method in the top-down composable contract that calls the method in the child contract. For example a top-down composable contract has a method called, “safeTransferChild” which will call the “safeTransferFrom” function in the child contract for you. If you have other authenticated methods you want to call in the child contract but there are no corresponding methods in the top-down composable then you are out of luck. You will have to transfer the child token out of the top-down composable and then call those methods directly on the child contract. Note that this disadvantage only applies to “regular ERC721 child contracts”. Authenticated methods can be called directly on child composable contracts.

Here’s a graphic that shows how top-down composables work:

Graphic created by Abhishek Chadha.

Bottom-Up Composables

Bottom-up composable contracts store information about parent tokens. Each bottom-up composable “knows” its parent token, if it has one. Unlike top-down composables, bottom-up composables do not store information about child tokens.

Bottom-up composables attach themselves as child tokens to other ERC721 tokens. They are a “clingy” type of composable.

Bottom-up composables treat regular ERC721 tokens like containers. For example 20 bottom-up composables could be transferred to a regular ERC721 token and the whole bunch of them could then be transferred simply by transferring the regular ERC721 token to someone else.

Bottom-up Advantages

1. A bottom-up composable can be transferred to any ERC721 token. Another way to say it is that a bottom-up composable can be a child of a regular ERC721 token.
2. Authenticated methods can be called directly on child bottom-up composable contracts.

Bottom-up Disadvantages

1. Regular ERC721 tokens cannot be child tokens of bottom-up composables. I say “regular ERC721 tokens” because bottom-up composables can be child tokens of other bottom-up composables.

I am not going to list bottom-up composable enumeration as an advantage or a disadvantage because it could be seen as both. Here is how it works: A bottom-up contract is supplied a parent ERC721 token and the contract returns all the child tokens it has for that parent. This means to get all the child tokens of a parent token you have to query every bottom-up contract that might have child tokens for it.

Here’s a graphic that shows how bottom-up composables work:

Graphic created by Abhishek Chadha.

Main Difference Summary

The main advantages and disadvantages of top-down and bottom-up approaches are opposites of each other. The main advantage of top-down composables is the main disadvantage of the bottom-up composables and vice versa.

The main advantage/disadvantage of both composable types is how they deal with regular ERC721 tokens. You can see that here:

1. Regular ERC721 tokens cannot be parent tokens of top-down composables, but they can be parent tokens of bottom-up composables.
2. Regular ERC721 tokens cannot be child tokens of bottom-up composables, but they can be child tokens of top-down composables.

When working with composables only (no regular ERC721 tokens) the main disadvantages of both kinds are gone.

Which Kind of Composable To Use?

If you want to transfer regular ERC721 tokens to non-fungible tokens, then use top-down composables.

If you want to transfer non-fungible tokens to regular ERC721 tokens then use bottom-up composables.

Can a token be both a Top-Down and Bottom-Up Composable?

Yes, this would mean implementing the functionality for both approaches for the same token.

Can a Top-Down Composable Own a Bottom-Up Composable and Vice-Versa?

Yes, the current ERC998 implementations of both approaches are interoperable with each other.

Where Can I Learn More About ERC998 Composables?

Read Matt Lockyer’s blog about them.

Check out the current implementations in the composables code repository.

Check out the draft of an EIP for ERC998 that is based on the current implementations of composables. This document explains technical details of both top-down composables and bottom-up composables.

Chat with us in the NFTy Magicians Discord server.

How Can I Help The ERC998 Standard or Implementation?

Yes, we are looking for help. Join the discord server.