ERC998 - Composable NFTs (cNFTs)

Overview

ERC998 enables Composable NFTs (cNFTs). NFTs that can own other NFTs, creating hierarchical ownership structures.

This implementation is built for Solidity 0.8.28 with modern security practices, based on the EIP-998 specification.

Key Benefits

• Hierarchical ownership: NFTs can own other NFTs and ERC20 tokens
• Safe transfers: Built-in security mechanisms with reentrancy protection
• Gas optimized: Efficient child management with depth limiting
• Standards compliant: Follows EIP-998 specification
• Modern Solidity: Built with Solidity 0.8.28 and OpenZeppelin 5.4.0

Articles

• Composable NFTs: Unlocking Complex Asset Management
• A Developer’s Guide to ERC998

Architecture

Core Components

• ERC998.sol: Main composable NFT contract
• IERC998ERC721TopDown.sol: Interface for ERC721 child management
• IERC998ERC20TopDown.sol: Interface for ERC20 child management
• IERC998ERC721TopDownEnumerable.sol: Enumerable interface for ERC721
• IERC998ERC20TopDownEnumerable.sol: Enumerable interface for ERC20

Features

NFT Management

• Child Addition/Removal: Add and remove child NFTs safely
• Hierarchical Transfers: Transfer child NFTs between parent NFTs
• Root Owner Tracking: Efficient root ownership identification
• ERC721 Receiver: Compliant with ERC721 transfer standards

Token Support

• ERC20 Integration: Support for ERC20 tokens as child assets
• Balance Management: Track ERC20 balances per NFT
• Safe Transfers: Use OpenZeppelin's SafeERC20 for token operations

Security Features

• Reentrancy Protection: Built with OpenZeppelin's ReentrancyGuard
• Safe Transfer Mechanisms: Prevents accidental loss of child NFTs
• Depth Limiting: Maximum nesting depth of 100 to prevent gas issues
• Access Control: Owner-only operations with proper validation

Demo

Curious how composability works in practice? This demo brings it to life by modeling a car as a structured digital asset using the ERC‑998 standard.

Try the simple demo now

Quick Start

Prerequisites

• Node.js >= 16
• npm or yarn
• MetaMask wallet or other Ethereum wallet

Installation

# Clone the repository & install dependencies
git clone https://github.com/maxnorm/composable-nft-erc998.git
cd composable-nft-erc998

npm install

# Compile contracts
npx hardhat compile

Testing

The project includes comprehensive tests covering all major functionality:

npx hardhat test
npx hardhat coverage

Test Coverage

• Deployment: Contract deployment and initialization
• Child Management: Adding, removing, and transferring child NFTs
• ERC20 Integration: Token balance management and transfers
• Security: Access control and edge case handling

Usage Examples

Basic Implementation

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import "./ERC998.sol";

contract MyComposableNFT is ERC998 {
    constructor() ERC998("MyComposable", "MCN") {}
    
    // Your custom logic here
}

Deployment

Local Development

# Start local blockchain (in another terminal)
npx hardhat node

# Deploy contracts
npx hardhat run scripts/deploy.ts --network localhost

Security Considerations

Built-in Protections

• Reentrancy Guard: Prevents reentrancy attacks
• Depth Limiting: Maximum nesting depth of 100 (this can be increased if needed, but be careful with gas costs for deep hierarchies)
• Safe Transfer Standards: Uses OpenZeppelin's safe transfer functions
• Use of OpenZeppelin Contracts: Battle-tested and audited

📖 References & Resources

• EIP-998
• ERC998 Issue
• ERC998.org
• Original ERC998 Implementation
• ERC721
• ERC20
• ERC6059
• ERC6059 Implementation
• OpenZeppelin Contracts

Contributors

@maxnorm

Special thanks to the original ERC998 & ERC6059 contributors for laying the foundation for composable NFTs.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors are not liable for any losses or damages incurred from the use of this code in any way.

Use at your own risk!

---

Built with ❤️ for the Ethereum family

---