The KREAd Character Builder is a decentralized application (dApp) live on the Agoric chain that enables the creation and handling of non-fungible tokens (NFTs) representing characters. These characters can be equipped with visual accessories, known as items, and both characters and items can be traded on a central marketplace or freely on other Agoric NFT dApps.
This article provides a detailed technical overview of the KREAd dApp, focusing on its concept, architecture, JavaScript smart contracts, key implementation details, and how it takes advantage of unique Agoric properties like offer safety to create a better user experience.
The Concept: Dynamic NFTs
Character and Item NFTs
The central idea of the KREAd Character Builder is the creation of NFTs representing characters and items those characters can hold and benefit from. Characters have a unique name, properties randomly selected at minting, and an inventory for items.
Items, on the other hand, are visual accessories like hair, masks, or backgrounds. When items are equipped to a character, they can impact the character’s underlying attributes, enhancing or changing some of the properties from minting. Both characters and items are NFTs, and they can be freely traded on various platforms.
Asset Composability and Component Library
One key feature of the Agoric developer experience is asset composability, allowing the reuse of existing contracts to support the dApp. For instance, Agoric’s sellItems contract can be used for listing assets in a marketplace application. This promotes code modularity and encourages developers to share custom code for common logic. Developers can combine these smart contracts with the growing Agoric Component Library to cut down the time to deploying code.
Agoric Offer Safety
A feature of the Agoric smart contract framework, Zoe, offer safety is emphasized to ensure trust and prevent potential issues. Users are encouraged to make use of the offer safety feature, which guarantees that they will receive the expected assets in return for their offers. This is particularly important when users accept offers with an empty "want" property, ensuring they get what they expect.
Thinking in Terms of Assets
The architecture encourages thinking in terms of assets, where identity is represented by objects, not credentials. Objects, such as NFTs, are used to represent privileges or access across dApps, allowing easy transfer of positions by transferring these objects.
Architecture of an Agoric Application
Agoric Smart Contract Composability
When designing an Agoric application, contract composability is a crucial consideration. Instead of writing an entire app in a custom smart contract, developers are encouraged to explore existing contracts that can support their dApp. For example, marketplace component from the Agoric Component Library can leverage the sellItems contract for listing assets, and later, the barterExchange contract for free trading of assets.
Offer Safety Guarantees
Offer safety is vital to build trust in Agoric apps. Ensuring that offers are constructed with safety guarantees helps users avoid potential issues. For example, users can use the offer safety feature to guarantee that they receive the expected assets by properly forming the "want" property in their offer.
Thinking in Terms of Assets
The architecture promotes a shift in mindset, encouraging developers to think in terms of assets rather than traditional identity approaches. This approach provides flexibility and opens up design possibilities. Developers are encouraged to explore the design options enabled by representing privileges or access through objects.
Hands on with KREAd’s JavaScript Smart Contracts
Quick Start
The following sections provide a step-by-step guide to setting up and running the KREAd Character Builder. The project is organized into two main directories:
/agoric: Contains the Agoric SDK, contract code, contract deployment script, and API deployment script.
/contract: Holds the contract code and contract deployment script.
/api: Contains the API deployment script.
/frontend: Consists of the React application, including the dApp UI, local bridge WebSocket connection, and constants file generated by the deployment scripts.
Contract Initialization
The initialization of the KREAd contract involves setting up external data required for its operation. The initConfig function is responsible for populating the contract state with the necessary input. This function is made available via the Creator Facet, ensuring that only the actor creating the instance has access to it.
This design allows for composability, as different instances of the contract can be configured with their own set of NFT data during initialization.
Asset Requirements
The KREAd project aims to create and handle non-fungible assets, following specific requirements:
Character and item NFTs must be immutable objects with a set of predefined properties.
Character NFTs must contain a unique name, passed by its creator.
A character’s properties must be randomly selected from a predefined set at the time of minting.
Character NFTs must be able to hold item NFTs.
Users must be allowed to store and withdraw item NFTs any number of times within a character NFT they own. Only a single item of each item category can be stored at once.
Asset Architecture
Set Up the Issuer Kit
The first step in creating NFTs is to set up the Issuer Kit using the Agoric SDK. The resulting brand, issuer, and mint objects for each asset are obtained by calling makeZCFMint.
This establishes the foundation for creating character and item NFTs.
Creating a Mint Invitation
To enable users to mint characters, the contract exposes a method through ZCF’s makeInvitation. This method is crucial for handling offer proposals and creating a credible Zoe invitation for a particular smart contract.
This design ensures that any user with a reference to the contract instance can obtain a mint invitation for characters.
Contract Mint Function
The mintCharacterNFT function is responsible for minting new characters. It incorporates various checks, such as ensuring the configuration is complete and verifying the structure of the proposal.
Mint Function:
This function encapsulates the entire process of character creation, ensuring that a new character NFT is minted along with default item NFTs.
Character Info and Item Info
The getCharacterInfo and getItemInfo functions retrieve the necessary information for character and item creation.
These functions ensure that characters are created with random properties and default items.
Create Character
The createCharacter function takes the character information and returns a new character object.
This function sets up the initial character object with the provided information.
Create Default Items
The createDefaultItems function takes item information and returns an array of default item objects.
This function creates default items based on the provided information.
Create Item
The createItem function takes item information and returns a new item object.
This function sets up the initial item object with the provided information.
Calculate Timestamp
The calculateTimestamp function generates a timestamp based on the provided seat.
This function ensures that each character NFT has a unique timestamp.
Create NFT
The createNFT function takes an object, issuer, and brand, and returns a new NFT.
This function is a generic NFT creation function that works for both characters and items.
Make Character Invitation
The makeCharacterInvitation function takes a character NFT and returns a new invitation.
This function ensures that a user is provided with a valid invitation after minting a new character NFT.
Discover Dynamic NFTs Built with JavaScript
The KREAd Character Builder is designed to provide users with a decentralized and flexible platform for creating, trading, and customizing characters and items. The implementation is built on the principles of contract composability, offer safety guarantees, and thinking in terms of assets. By leveraging the Agoric SDK and adopting a modular architecture, the dApp encourages collaboration and reuse of existing smart contracts.
Developers interested in exploring the KREAd Character Builder can refer to the provided quick start guide to set up and run the project. The codebase is organized into directories, each serving a specific purpose, making it easy to understand and extend. The asset architecture ensures that character and item NFTs adhere to specific requirements, promoting consistency and interoperability.
Overall, the KREAd Character Builder demonstrates how decentralized applications can be designed and implemented on the Agoric platform, offering users a seamless and secure experience in the creation and trading of NFTs.
Interested in building web3 applications using JavaScript smart contracts? Subscribe to our developer newsletter for more technical deep dives like this one, plus be the first to know about workshops and webinars.
