Skip to main content
Version: 0.42

8. Marketplace

In this tutorial, we're going to create a marketplace that uses both the fungible and non-fungible token (NFTs) contracts that we have learned about in previous tutorials. This is only for educational purposes and is not meant to be used in production See a production-ready marketplace in the NFT storefront repo. This contract is already deployed to testnet and mainnet and can be used by anyone for any generic NFT sale!


tip

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

https://play.onflow.org/49ec2856-1258-4675-bac3-850b4bae1929


The tutorial will be asking you to take various actions to interact with this code. The marketplace setup guide shows you how to get the playground set up to do this tutorial.

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.

Marketplaces are a popular application of blockchain technology and smart contracts. When there are NFTs in existence, users usually want to be able to buy and sell them with their fungible tokens.

Now that there is an example for both fungible and non-fungible tokens, we can build a marketplace that uses both. This is referred to as composability: the ability for developers to leverage shared resources, such as code or userbases, and use them as building blocks for new applications.

Flow is designed to enable composability because of the way that interfaces, resources and capabilities are designed.

  • Interfaces allow projects to support any generic type as long as it supports a standard set of functionality specified by an interface.
  • Resources can be passed around and owned by accounts, contracts or even other resources, unlocking different use cases depending on where the resource is stored.
  • Capabilities allow exposing user-defined sets of functionality through special objects that enforce strict security with Cadence's type system.

The combination of these allows developers to do more with less, re-using known safe code and design patterns to create new, powerful, and unique interactions!

Action

At some point before or after this tutorial, you should definitely check out the formal documentation linked above about interfaces, resources, and capabilities. It will help complete your understanding of these complex, but powerful features.

To create a marketplace, we need to integrate the functionality of both fungible and non-fungible tokens into a single contract that gives users control over their money and assets. To accomplish this, we're going to take you through these steps to create a composable smart contract and get comfortable with the marketplace:

  1. Ensure that your fungible token and non-fungible token contracts are deployed and set up correctly.
  2. Deploy the marketplace type declarations to account 0x03.
  3. Create a marketplace object and store it in your account storage, putting an NFT up for sale and publishing a public capability for your sale.
  4. Use a different account to purchase the NFT from the sale.
  5. Run a script to verify that the NFT was purchased.

Before proceeding with this tutorial, you need to complete the Fungible Tokens and Non-Fungible Token tutorials to understand the building blocks of this smart contract.

Marketplace Design


One way to implement a marketplace is to have a central smart contract that users deposit their NFTs and their price into, and have anyone come by and be able to buy the token for that price. This approach is reasonable, but it centralizes the process and takes away options from the owners. We want users to be able to maintain ownership of the NFTs that they are trying to sell while they are trying to sell them.

Instead of taking this centralized approach, each user can list a sale from within their own account.

Then, users could either provide a link to their sale to an application that can list it centrally on a website, or to a central sale aggregator smart contract if they want the entire transaction to stay on-chain. This way, the owner of the token keeps custody of their token while it is on sale.

Action

Before we start, we need to confirm the state of your accounts.
If you haven't already, please perform the steps in the marketplace setup guide to ensure that the Fungible Token and Non-Fungible Token contracts are deployed to account 1 and 2 and own some tokens.
Your accounts should look like this:

Action

You can run the 1. CheckSetupScript.cdc script to ensure that your accounts are correctly set up:

CheckSetupScript.cdc

_63
// CheckSetupScript.cdc
_63
_63
import ExampleToken from 0x01
_63
import ExampleNFT from 0x02
_63
_63
// This script checks that the accounts are set up correctly for the marketplace tutorial.
_63
//
_63
// Account 0x01: Vault Balance = 40, NFT.id = 1
_63
// Account 0x02: Vault Balance = 20, No NFTs
_63
access(all)
_63
fun main() {
_63
// Get the accounts' public account objects
_63
let acct1 = getAccount(0x01)
_63
let acct2 = getAccount(0x02)
_63
_63
// Get references to the account's receivers
_63
// by getting their public capability
_63
// and borrowing a reference from the capability
_63
let acct1ReceiverRef = acct1.getCapability(/public/CadenceFungibleTokenTutorialReceiver)
_63
.borrow<&ExampleToken.Vault{ExampleToken.Balance}>()
_63
?? panic("Could not borrow acct1 vault reference")
_63
_63
let acct2ReceiverRef = acct2.getCapability(/public/CadenceFungibleTokenTutorialReceiver)
_63
.borrow<&ExampleToken.Vault{ExampleToken.Balance}>()
_63
?? panic("Could not borrow acct2 vault reference")
_63
_63
// Log the Vault balance of both accounts and ensure they are
_63
// the correct numbers.
_63
// Account 0x01 should have 40.
_63
// Account 0x02 should have 20.
_63
log("Account 1 Balance")
_63
log(acct1ReceiverRef.balance)
_63
log("Account 2 Balance")
_63
log(acct2ReceiverRef.balance)
_63
_63
// verify that the balances are correct
_63
if acct1ReceiverRef.balance != 40.0 || acct2ReceiverRef.balance != 20.0 {
_63
panic("Wrong balances!")
_63
}
_63
_63
// Find the public Receiver capability for their Collections
_63
let acct1Capability = acct1.getCapability(ExampleNFT.CollectionPublicPath)
_63
let acct2Capability = acct2.getCapability(ExampleNFT.CollectionPublicPath)
_63
_63
// borrow references from the capabilities
_63
let nft1Ref = acct1Capability.borrow<&{ExampleNFT.NFTReceiver}>()
_63
?? panic("Could not borrow acct1 nft collection reference")
_63
_63
let nft2Ref = acct2Capability.borrow<&{ExampleNFT.NFTReceiver}>()
_63
?? panic("Could not borrow acct2 nft collection reference")
_63
_63
// Print both collections as arrays of IDs
_63
log("Account 1 NFTs")
_63
log(nft1Ref.getIDs())
_63
_63
log("Account 2 NFTs")
_63
log(nft2Ref.getIDs())
_63
_63
// verify that the collections are correct
_63
if nft1Ref.getIDs()[0] != 1 || nft2Ref.getIDs().length != 0 {
_63
panic("Wrong Collections!")
_63
}
_63
}

You should see something similar to this output if your accounts are set up correctly. They are in the same state that they would have been in if you followed the Fungible Tokens and Non-Fungible Tokens tutorials in succession:


_10
"Account 1 Balance"
_10
40.00000000
_10
"Account 2 Balance"
_10
20.00000000
_10
"Account 1 NFTs"
_10
[1]
_10
"Account 2 NFTs"
_10
[]

Now that your accounts are in the correct state, we can build a marketplace that enables the sale of NFT's between accounts.

Setting up an NFT Marketplace


Every user who wants to sell an NFT will store an instance of a SaleCollection resource in their account storage.

Time to deploy the marketplace contract:

Action
  1. Switch to the ExampleMarketplace contract (Contract 3).
  2. With ExampleMarketplace.cdc open, select account 0x03 from the deployment modal in the bottom right and deploy.

ExampleMarketplace.cdc should contain the following contract definition:

ExampleMarketplace.cdc

_176
import ExampleToken from 0x01
_176
import ExampleNFT from 0x02
_176
_176
// ExampleMarketplace.cdc
_176
//
_176
// The ExampleMarketplace contract is a very basic sample implementation of an NFT ExampleMarketplace on Flow.
_176
//
_176
// This contract allows users to put their NFTs up for sale. Other users
_176
// can purchase these NFTs with fungible tokens.
_176
//
_176
// Learn more about marketplaces in this tutorial: https://developers.flow.com/cadence/tutorial/marketplace-compose
_176
//
_176
// This contract is a learning tool and is not meant to be used in production.
_176
// See the NFTStorefront contract for a generic marketplace smart contract that
_176
// is used by many different projects on the Flow blockchain:
_176
//
_176
// https://github.com/onflow/nft-storefront
_176
_176
access(all)
_176
contract ExampleMarketplace {
_176
_176
// Event that is emitted when a new NFT is put up for sale
_176
access(all)
_176
event ForSale(id: UInt64, price: UFix64, owner: Address?)
_176
_176
// Event that is emitted when the price of an NFT changes
_176
access(all)
_176
event PriceChanged(id: UInt64, newPrice: UFix64, owner: Address?)
_176
_176
// Event that is emitted when a token is purchased
_176
access(all)
_176
event TokenPurchased(id: UInt64, price: UFix64, seller: Address?, buyer: Address?)
_176
_176
// Event that is emitted when a seller withdraws their NFT from the sale
_176
access(all)
_176
event SaleCanceled(id: UInt64, seller: Address?)
_176
_176
// Interface that users will publish for their Sale collection
_176
// that only exposes the methods that are supposed to be public
_176
//
_176
access(all)
_176
resource interface SalePublic {
_176
_176
access(all)
_176
fun purchase(tokenID: UInt64, recipient: Capability<&AnyResource{ExampleNFT.NFTReceiver}>, buyTokens: @ExampleToken.Vault)
_176
_176
access(all)
_176
fun idPrice(tokenID: UInt64): UFix64?
_176
_176
access(all)
_176
fun getIDs(): [UInt64]
_176
}
_176
_176
// SaleCollection
_176
//
_176
// NFT Collection object that allows a user to put their NFT up for sale
_176
// where others can send fungible tokens to purchase it
_176
//
_176
access(all)
_176
resource SaleCollection: SalePublic {
_176
_176
/// A capability for the owner's collection
_176
access(self)
_176
var ownerCollection: Capability<&ExampleNFT.Collection>
_176
_176
// Dictionary of the prices for each NFT by ID
_176
access(self)
_176
var prices: {UInt64: UFix64}
_176
_176
// The fungible token vault of the owner of this sale.
_176
// When someone buys a token, this resource can deposit
_176
// tokens into their account.
_176
access(account)
_176
let ownerVault: Capability<&AnyResource{ExampleToken.Receiver}>
_176
_176
init (ownerCollection: Capability<&ExampleNFT.Collection>,
_176
ownerVault: Capability<&AnyResource{ExampleToken.Receiver}>) {
_176
_176
pre {
_176
// Check that the owner's collection capability is correct
_176
ownerCollection.check():
_176
"Owner's NFT Collection Capability is invalid!"
_176
_176
// Check that the fungible token vault capability is correct
_176
ownerVault.check():
_176
"Owner's Receiver Capability is invalid!"
_176
}
_176
self.ownerCollection = ownerCollection
_176
self.ownerVault = ownerVault
_176
self.prices = {}
_176
}
_176
_176
// cancelSale gives the owner the opportunity to cancel a sale in the collection
_176
access(all)
_176
fun cancelSale(tokenID: UInt64) {
_176
// remove the price
_176
self.prices.remove(key: tokenID)
_176
self.prices[tokenID] = nil
_176
_176
// Nothing needs to be done with the actual token because it is already in the owner's collection
_176
}
_176
_176
// listForSale lists an NFT for sale in this collection
_176
access(all)
_176
fun listForSale(tokenID: UInt64, price: UFix64) {
_176
pre {
_176
self.ownerCollection.borrow()!.idExists(id: tokenID):
_176
"NFT to be listed does not exist in the owner's collection"
_176
}
_176
// store the price in the price array
_176
self.prices[tokenID] = price
_176
_176
emit ForSale(id: tokenID, price: price, owner: self.owner?.address)
_176
}
_176
_176
// changePrice changes the price of a token that is currently for sale
_176
access(all)
_176
fun changePrice(tokenID: UInt64, newPrice: UFix64) {
_176
self.prices[tokenID] = newPrice
_176
_176
emit PriceChanged(id: tokenID, newPrice: newPrice, owner: self.owner?.address)
_176
}
_176
_176
// purchase lets a user send tokens to purchase an NFT that is for sale
_176
access(all)
_176
fun purchase(tokenID: UInt64, recipient: Capability<&AnyResource{ExampleNFT.NFTReceiver}>, buyTokens: @ExampleToken.Vault) {
_176
pre {
_176
self.prices[tokenID] != nil:
_176
"No token matching this ID for sale!"
_176
buyTokens.balance >= (self.prices[tokenID] ?? 0.0):
_176
"Not enough tokens to by the NFT!"
_176
recipient.borrow != nil:
_176
"Invalid NFT receiver capability!"
_176
}
_176
_176
// get the value out of the optional
_176
let price = self.prices[tokenID]!
_176
_176
self.prices[tokenID] = nil
_176
_176
let vaultRef = self.ownerVault.borrow()
_176
?? panic("Could not borrow reference to owner token vault")
_176
_176
// deposit the purchasing tokens into the owners vault
_176
vaultRef.deposit(from: <-buyTokens)
_176
_176
// borrow a reference to the object that the receiver capability links to
_176
// We can force-cast the result here because it has already been checked in the pre-conditions
_176
let receiverReference = receiver.borrow()!
_176
_176
// deposit the NFT into the buyers collection
_176
receiverReference.deposit(token: <-self.ownerCollection.borrow()!.withdraw(withdrawID: tokenID))
_176
_176
emit TokenPurchased(id: tokenID, price: price, owner: self.owner?.address, buyer: receiverReference.owner?.address)
_176
}
_176
_176
// idPrice returns the price of a specific token in the sale
_176
access(all)
_176
fun idPrice(tokenID: UInt64): UFix64? {
_176
return self.prices[tokenID]
_176
}
_176
_176
// getIDs returns an array of token IDs that are for sale
_176
access(all)
_176
fun getIDs(): [UInt64] {
_176
return self.prices.keys
_176
}
_176
}
_176
_176
// createCollection returns a new collection resource to the caller
_176
access(all)
_176
fun createSaleCollection(ownerCollection: Capability<&ExampleNFT.Collection>,
_176
ownerVault: Capability<&AnyResource{ExampleToken.Receiver}>): @SaleCollection {
_176
return <- create SaleCollection(ownerCollection: ownerCollection, ownerVault: ownerVault)
_176
}
_176
}

This marketplace contract has resources that function similarly to the NFT Collection that was explained in Non-Fungible Tokens, with a few differences and additions:

  • This marketplace contract has methods to add and remove NFTs, but instead of storing the NFT resource object in the sale collection, the user provides a capability to their main collection that allows the listed NFT to be withdrawn and transferred when it is purchased. When a user wants to put their NFT up for sale, they do so by providing the ID and the price to the listForSale function. Then, another user can call the purchase method, sending their ExampleToken.Vault that contains the currency they are using to make the purchase. The buyer also includes a capability to their NFT ExampleNFT.Collection so that the purchased token can be immediately deposited into their collection when the purchase is made.
  • This marketplace contract stores a capability: access(all) let ownerVault: Capability<&AnyResource{FungibleToken.Receiver}>. The owner of the sale saves a capability to their Fungible Token Receiver within the sale. This allows the sale resource to be able to immediately deposit the currency that was used to buy the NFT into the owners Vault when a purchase is made.
  • This marketplace contract includes events. Cadence supports defining events within contracts that can be emitted when important actions happen. External apps can monitor these events to know the state of the smart contract.

_15
// Event that is emitted when a new NFT is put up for sale
_15
access(all)
_15
event ForSale(id: UInt64, price: UFix64, owner: Address?)
_15
_15
// Event that is emitted when the price of an NFT changes
_15
access(all)
_15
event PriceChanged(id: UInt64, newPrice: UFix64, owner: Address?)
_15
_15
// Event that is emitted when a token is purchased
_15
access(all)
_15
event TokenPurchased(id: UInt64, price: UFix64, seller: Address?, buyer: Address?)
_15
_15
// Event that is emitted when a seller withdraws their NFT from the sale
_15
access(all)
_15
event SaleCanceled(id: UInt64, seller: Address?)

This contract has a few new features and concepts that are important to cover:

Events

Events are special values that can be emitted during the execution of a program. They usually contain information to indicate that some important action has happened in a smart contract, such as an NFT transfer, a permission change, or many other different things. Off-chain applications can monitor events using a Flow SDK to know what is happening on-chain without having to query a smart contract directly.

Many applications want to maintain an off-chain record of what is happening on-chain so they can have faster performance when getting information about their users' accounts or generating analytics.

Events are declared by indicating the access level, event, and the name and parameters of the event, like a function declaration:


_10
access(all)
_10
event ForSale(id: UInt64, price: UFix64, owner: Address?)

Events cannot modify state at all; they indicate when important actions happen in the smart contract.

Events are emitted with the emit keyword followed by the invocation of the event as if it were a function call.


_10
emit ForSale(id: tokenID, price: price, owner: self.owner?.address)

External applications can monitor the blockchain to take action when certain events are emitted.

Resource-Owned Capabilities

We have covered capabilities in previous tutorials, but only the basics. Capabilities can be used for so much more!

As you hopefully understand, capabilites are links to private objects in account storage that specify and expose a subset in the public or private namespace of public or private paths where the Capability is linked.

To create a capability, a user typically uses the AuthAccount.link method to create a link to a resource in their private storage, specifying a type to link the capability as:


_10
// Create a public Receiver + Balance capability to the Vault
_10
// acct is an `AuthAccount`
_10
// The object being linked to has to be an `ExampleToken.Vault`,
_10
// and the link only exposes the fields in the `ExampleToken.Receiver` and `ExampleToken.Balance` interfaces.
_10
acct.link<&ExampleToken.Vault{ExampleToken.Receiver, ExampleToken.Balance}>
_10
(/public/CadenceFungibleTokenTutorialReceiver, target: /storage/CadenceFungibleTokenTutorialVault)

Then, users can get that capability if it was created in a public path, borrow it, and access the functionality that the owner specified.


_14
// Get account 0x01's PublicAccount object
_14
let publicAccount = getAccount(0x01)
_14
_14
// Retrieve a Vault Receiver Capability from the account's public storage
_14
let acct1Capability = acct.getCapability<&AnyResource{ExampleToken.Receiver}>(
_14
/public/CadenceFungibleTokenTutorialReceiver
_14
)
_14
_14
// Borrow a reference
_14
let acct1ReceiverRef = acct1Capability.borrow()
_14
?? panic("Could not borrow a receiver reference to the vault")
_14
_14
// Deposit tokens
_14
acct1ReceiverRef.deposit(from: <-tokens)

With the marketplace contract, we are utilizing a new feature of capabilities. Capabilities can be stored anywhere! Lots of functionality is contained within resources, and developers will sometimes want to be able to access some of the functionality of resources from within different resources or contracts.

We store two different capabilities in the marketplace sale collection:


_10
/// A capability for the owner's collection
_10
access(self)
_10
var ownerCollection: Capability<&ExampleNFT.Collection>
_10
_10
// The fungible token vault of the owner of this sale.
_10
// When someone buys a token, this resource can deposit
_10
// tokens into their account.
_10
access(account)
_10
let ownerVault: Capability<&AnyResource{ExampleToken.Receiver}>

If an object like a contract or resource owns a capability, they can borrow a reference to that capability at any time to access that functionality without having to get it from the owner's account every time.

This is especially important if the owner wants to expose some functionality that is only intended for one person, meaning that the link for the capability is not stored in a public path. We do that in this example, because the sale collection stores a capability that can access all of the functionality of the ExampleNFT.Collection. It needs this because it withdraws the specified NFT in the purchase() method to send to the buyer.

It is important to remember that control of a capability does not equal ownership of the underlying resource. You can use the capability to access that resource's functionality, but you can't use it to fake ownership. You need the actual resource (identified by the prefixed @ symbol) to prove ownership.

Additionally, these capabilities can be stored anywhere, but if a user decides that they no longer want the capability to be used, they can revoke it with the AuthAccount.unlink() method so any capabilities that use that link are rendered invalid.

One last piece to consider about capabilities is the decision about when to use them instead of storing the resource directly. This tutorial used to have the SaleCollection directly store the NFTs that were for sale, like so:


_10
access(all)
_10
resource SaleCollection: SalePublic {
_10
_10
/// Dictionary of NFT objects for sale
_10
/// Maps ID to NFT resource object
_10
/// Not recommended
_10
access(self)
_10
var forSale: @{UInt64: ExampleNFT.NFT}
_10
}

This is a logical way to do it, and illustrates another important concept in Cadence, that resources can own other resources! Check out the Kitty Hats tutorial for a little more exploration of this concept.

In this case however, nesting resources doesn't make sense. If a user decides to store their for-sale NFTs in a separate place from their main collection, then those NFTs are not available to be shown to any app or smart contract that queries the main collection, so it is as if the owner doesn't actually own the NFT!

In cases like this, we usually recommend using a capability to the main collection so that the main collection can remain unchanged and fully usable by other smart contracts and apps. This also means that if a for-sale NFT gets transferred by some means other than a purchase, then you need a way to get rid of the stale listing. That is out of the scope of this tutorial though.

Enough explaining! Lets execute some code!

Using the Marketplace

At this point, we should have an ExampleToken.Vault and an Example.NFT.Collection in both accounts' storage. Account 0x01 should have an NFT in their collection and the ExampleMarketplace contract should be deployed to 0x03.

You can create a SaleCollection and list account 0x01's token for sale by following these steps:

Action
  1. Open Transaction 4, CreateSale.cdc
  2. Select account 0x01 as the only signer and click the Send button to submit the transaction.
Transaction4.cdc

_36
// CreateSale.cdc
_36
_36
import ExampleToken from 0x01
_36
import ExampleNFT from 0x02
_36
import ExampleMarketplace from 0x03
_36
_36
// This transaction creates a new Sale Collection object,
_36
// lists an NFT for sale, puts it in account storage,
_36
// and creates a public capability to the sale so that others can buy the token.
_36
transaction {
_36
_36
prepare(acct: AuthAccount) {
_36
_36
// Borrow a reference to the stored Vault
_36
let receiver = acct.getCapability<&{ExampleToken.Receiver}>(/public/CadenceFungibleTokenTutorialReceiver)
_36
_36
// borrow a reference to the nftTutorialCollection in storage
_36
let collectionCapability = acct.link<&ExampleNFT.Collection>(/private/nftTutorialCollection, target: ExampleNFT.CollectionStoragePath)
_36
?? panic("Unable to create private link to NFT Collection")
_36
_36
// Create a new Sale object,
_36
// initializing it with the reference to the owner's vault
_36
let sale <- ExampleMarketplace.createSaleCollection(ownerCollection: collectionCapability, ownerVault: receiver)
_36
_36
// List the token for sale by moving it into the sale object
_36
sale.listForSale(tokenID: 1, price: 10.0)
_36
_36
// Store the sale object in the account storage
_36
acct.storage.save(<-sale, to: /storage/NFTSale)
_36
_36
// Create a public capability to the sale so that others can call its methods
_36
acct.link<&ExampleMarketplace.SaleCollection{ExampleMarketplace.SalePublic}>(/public/NFTSale, target: /storage/NFTSale)
_36
_36
log("Sale Created for account 1. Selling NFT 1 for 10 tokens")
_36
}
_36
}

This transaction:

  1. Gets a Receiver capability on the owners Vault.
  2. Gets a private ExampleNFT.Collection Capability from the owner.
  3. Creates the SaleCollection, which stores their Vault and ExampleNFT.Collection capabilities.
  4. Lists the token with ID = 1 for sale and sets its price as 10.0.
  5. Stores the SaleCollection in their account storage and links a public capability that allows others to purchase any NFTs for sale.

Let's run a script to ensure that the sale was created correctly.

  1. Open Script 2: GetSaleIDs.cdc
  2. Click the Execute button to print the ID and price of the NFT that account 0x01 has for sale.
GetSaleIDs.cdc

_23
// GetSaleIDs.cdc
_23
_23
import ExampleToken from 0x01
_23
import ExampleNFT from 0x02
_23
import ExampleMarketplace from 0x03
_23
_23
// This script prints the NFTs that account 0x01 has for sale.
_23
access(all)
_23
fun main() {
_23
// Get the public account object for account 0x01
_23
let account1 = getAccount(0x01)
_23
_23
// Find the public Sale reference to their Collection
_23
let acct1saleRef = account1.getCapability(/public/NFTSale)
_23
.borrow<&AnyResource{ExampleMarketplace.SalePublic}>()
_23
?? panic("Could not borrow acct2 nft sale reference")
_23
_23
// Los the NFTs that are for sale
_23
log("Account 1 NFTs for sale")
_23
log(acct1saleRef.getIDs())
_23
log("Price")
_23
log(acct1saleRef.idPrice(tokenID: 1))
_23
}

This script should complete and print something like this:


_10
"Account 1 NFTs for sale"
_10
[1]
_10
"Price"
_10
10

Purchasing an NFT


The buyer can now purchase the seller's NFT by using the transaction in Transaction2.cdc:

Action
  1. Open Transaction 5: PurchaseSale.cdc file
  2. Select account 0x02 as the only signer and click the Send button
PurchaseSale.cdc

_46
// PurchaseSale.cdc
_46
_46
import ExampleToken from 0x01
_46
import ExampleNFT from 0x02
_46
import ExampleMarketplace from 0x03
_46
_46
// This transaction uses the signers Vault tokens to purchase an NFT
_46
// from the Sale collection of account 0x01.
_46
transaction {
_46
_46
// Capability to the buyer's NFT collection where they
_46
// will store the bought NFT
_46
let collectionCapability: Capability<&AnyResource{ExampleNFT.NFTReceiver}>
_46
_46
// Vault that will hold the tokens that will be used to
_46
// but the NFT
_46
let temporaryVault: @ExampleToken.Vault
_46
_46
prepare(acct: AuthAccount) {
_46
_46
// get the references to the buyer's fungible token Vault and NFT Collection Receiver
_46
self.collectionCapability = acct.getCapability<&AnyResource{ExampleNFT.NFTReceiver}>(from: ExampleNFT.CollectionPublicPath)
_46
_46
let vaultRef = acct.borrow<&ExampleToken.Vault>(from: /storage/CadenceFungibleTokenTutorialVault)
_46
?? panic("Could not borrow owner's vault reference")
_46
_46
// withdraw tokens from the buyers Vault
_46
self.temporaryVault <- vaultRef.withdraw(amount: 10.0)
_46
}
_46
_46
execute {
_46
// get the read-only account storage of the seller
_46
let seller = getAccount(0x01)
_46
_46
// get the reference to the seller's sale
_46
let saleRef = seller.getCapability(/public/NFTSale)!
_46
.borrow<&AnyResource{ExampleMarketplace.SalePublic}>()
_46
?? panic("Could not borrow seller's sale reference")
_46
_46
// purchase the NFT the seller is selling, giving them the capability
_46
// to your NFT collection and giving them the tokens to buy it
_46
saleRef.purchase(tokenID: 1, recipient: self.collectionCapability, buyTokens: <-self.temporaryVault)
_46
_46
log("Token 1 has been bought by account 2!")
_46
}
_46
}

This transaction:

  1. Gets the capability to the buyer's NFT receiver
  2. Get a reference to their token vault and withdraws the sale purchase amount
  3. Gets the public account object for account 0x01
  4. Gets the reference to the seller's public sale
  5. Calls the purchase function, passing in the tokens and the Collection reference. Then purchase deposits the bought NFT directly into the buyer's collection.

Verifying the NFT Was Purchased Correctly


You can run now run a script to verify that the NFT was purchased correctly because:

  • account 0x01 has 50 tokens and does not have any NFTs for sale or in their collection and account
  • account 0x02 has 10 tokens and an NFT with id=1

To run a script that verifies the NFT was purchased correctly, follow these steps:

Action
  1. Open Script 3: VerifyAfterPurchase.cdc
  2. Click the Execute button

VerifyAfterPurchase.cdc should contain the following code:

Script3.cdc

_75
// VerifyAfterPurchase.cdc
_75
_75
import ExampleToken from 0x01
_75
import ExampleNFT from 0x02
_75
import ExampleMarketplace from 0x03
_75
_75
// This script checks that the Vault balances and NFT collections are correct
_75
// for both accounts.
_75
//
_75
// Account 1: Vault balance = 50, No NFTs
_75
// Account 2: Vault balance = 10, NFT ID=1
_75
access(all)
_75
fun main() {
_75
// Get the accounts' public account objects
_75
let acct1 = getAccount(0x01)
_75
let acct2 = getAccount(0x02)
_75
_75
// Get references to the account's receivers
_75
// by getting their public capability
_75
// and borrowing a reference from the capability
_75
let acct1ReceiverRef = acct1.capabilities
_75
.borrow<&ExampleToken.Vault{ExampleToken.Balance}>(/public/CadenceFungibleTokenTutorialReceiver)
_75
?? panic("Could not borrow acct1 vault reference")
_75
_75
let acct2ReceiverRef = acct2.capabilities
_75
.borrow<&ExampleToken.Vault{ExampleToken.Balance}>(/public/CadenceFungibleTokenTutorialReceiver)
_75
?? panic("Could not borrow acct2 vault reference")
_75
_75
// Log the Vault balance of both accounts and ensure they are
_75
// the correct numbers.
_75
// Account 0x01 should have 50.
_75
// Account 0x02 should have 10.
_75
log("Account 1 Balance")
_75
log(acct1ReceiverRef.balance)
_75
log("Account 2 Balance")
_75
log(acct2ReceiverRef.balance)
_75
_75
// verify that the balances are correct
_75
if acct1ReceiverRef.balance != 50.0 || acct2ReceiverRef.balance != 10.0 {
_75
panic("Wrong balances!")
_75
}
_75
_75
// Find the public Receiver capability for their Collections
_75
let acct1Capability = acct1.getCapability(ExampleNFT.CollectionPublicPath)
_75
let acct2Capability = acct2.getCapability(ExampleNFT.CollectionPublicPath)
_75
_75
// borrow references from the capabilities
_75
let nft1Ref = acct1Capability.borrow<&{ExampleNFT.NFTReceiver}>()
_75
?? panic("Could not borrow acct1 nft collection reference")
_75
_75
let nft2Ref = acct2Capability.borrow<&{ExampleNFT.NFTReceiver}>()
_75
?? panic("Could not borrow acct2 nft collection reference")
_75
_75
// Print both collections as arrays of IDs
_75
log("Account 1 NFTs")
_75
log(nft1Ref.getIDs())
_75
_75
log("Account 2 NFTs")
_75
log(nft2Ref.getIDs())
_75
_75
// verify that the collections are correct
_75
if nft2Ref.getIDs()[0] != 1 || nft1Ref.getIDs().length != 0 {
_75
panic("Wrong Collections!")
_75
}
_75
_75
// Get the public sale reference for Account 0x01
_75
let acct1SaleRef = acct1.getCapability(/public/NFTSale)
_75
.borrow<&AnyResource{ExampleMarketplace.SalePublic}>()
_75
?? panic("Could not borrow acct1 nft sale reference")
_75
_75
// Print the NFTs that account 0x01 has for sale
_75
log("Account 1 NFTs for sale")
_75
log(acct1SaleRef.getIDs())
_75
if acct1SaleRef.getIDs().length != 0 { panic("Sale should be empty!") }
_75
}

If you did everything correctly, the transaction should succeed and it should print something similar to this:


_10
"Account 1 Vault Balance"
_10
50
_10
"Account 2 Vault Balance"
_10
10
_10
"Account 1 NFTs"
_10
[]
_10
"Account 2 NFTs"
_10
[1]
_10
"Account 1 NFTs for Sale"
_10
[]

Congratulations, you have successfully implemented a simple marketplace in Cadence and used it to allow one account to buy an NFT from another!

Scaling the Marketplace


A user can hold a sale in their account with these resources and transactions. Support for a central marketplace where users can discover sales is relatively easy to implement and can build on what we already have. If we wanted to build a central marketplace on-chain, we could use a contract that looks something like this:

CentralMarketplace.cdc

_27
// Marketplace would be the central contract where people can post their sale
_27
// references so that anyone can access them
_27
access(all)
_27
contract Marketplace {
_27
// Data structure to store active sales
_27
access(all)
_27
var tokensForSale: {Address: Capability<&SaleCollection>)}
_27
_27
// listSaleCollection lists a users sale reference in the array
_27
// and returns the index of the sale so that users can know
_27
// how to remove it from the marketplace
_27
access(all)
_27
fun listSaleCollection(collection: Capability<&SaleCollection>) {
_27
let saleRef = collection.borrow()
_27
?? panic("Invalid sale collection capability")
_27
_27
self.tokensForSale[saleRef.owner!.address] = collection
_27
}
_27
_27
// removeSaleCollection removes a user's sale from the array
_27
// of sale references
_27
access(all)
_27
fun removeSaleCollection(owner: Address) {
_27
self.tokensForSale[owner] = nil
_27
}
_27
_27
}

This contract isn't meant to be a working or production-ready contract, but it could be extended to make a complete central marketplace by having:

  • Sellers list a capability to their SaleCollection in this contract
  • Other functions that buyers could call to get info about all the different sales and to make purchases.

A central marketplace in an off-chain application is easier to implement because:

  • The app could host the marketplace and a user would simply log in to the app and give the app its account address.
  • The app could read the user's public storage and find their sale reference.
  • With the sale reference, the app could get all the information they need about how to display the sales on their website.
  • Any buyer could discover the sale in the app and login with their account, which gives the app access to their public references.
  • When the buyer wants to buy a specific NFT, the app would automatically generate the proper transaction to purchase the NFT from the seller.

Creating a Marketplace for Any Generic NFT


The previous examples show how a simple marketplace could be created for a specific class of NFTs. However, users will want to have a marketplace where they can buy and sell any NFT they want, regardless of its type. There are a few good examples of generic marketplaces on Flow right now.

  • The Flow team has created a completely decentralized example of a generic marketplace in the NFT storefront repo. This contract is already deployed to testnet and mainnet and can be used by anyone for any generic NFT sale!
  • VIV3 is a company that has a generic NFT marketplace.

Composable Resources on Flow


Now that you have an understanding of how composable smart contracts and the marketplace work on Flow, you're ready to play with composable resources! Check out the Kitty Hats tutorial!