🐚
shell
Engines
🚗

Engines

Engines are community-authored smart contracts that determine how the NFTs they power look and behave.

Developers can build portable, multi-tenanted, and hot-swappable engines to build complex NFT products without violating the expected end-user functionality of NFTs.

💡
If shell is an NFT operating system, engines are the apps.

Overview

shell separates the app-level business logic of an NFT (minting, rendering metadata, computing royalties, etc) from the standard token contract implementation.

This separate business logic is implemented as a smart contract known as a shell engine.

A single engine may be powering several shell collections at once. This is similar to how apps can be installed on several devices at once.

Forks

Each NFT belongs to a fork, and each fork is running an engine. A single shell NFT collection may have several active forks, each containing several NFTs and running different engines.

The owner of a fork may swap out the engine the fork is running at any time, changing the functionality and appearance of all NFTs in the fork.

💡
Permissionless iteration and competition is a core pillar of shell’s design. Instead of centralizing product development, shell allows all NFT owners to iterate on the NFT product that they own.

Storage

Data can be written by an engine to either NFT storage or fork storage, both of which are physically persisted in the NFT collection, not the engine contract.

Data isn’t lost when an engine is upgraded or swapped out, and data from any fork can be read (but not written) by any other fork.

What an engine can do

An engine CAN:

  • Prevent itself from being installed to a fork
  • Modify anything in fork storage for the fork its installed to

For a given NFT belonging to a fork running a specific engine, that engine CAN:

  • Determine how the NFT looks and what its metadata is (name, description, properties)
  • Determine how royalties are computed (via ERC-2981)
  • Determine how NFTs are minted 1️⃣
  • Write the initial, immutable mint data to the NFT 1️⃣
  • Modify anything in the NFT's token storage
  • Execute on-chain code every time a transfer occurs (including mints and burns)
    • The engine has the opportunity to prevent transfers by reverting in this hook
1️⃣
The engine installed to the root fork is the only engine that can mint in the collection

What an engine cannot do

An engine CANNOT:

  • Unilaterally transfer or burn an NFT
  • Modify the initial mint data of a token
  • Modify framework data associated with a token or collection
  • Issue token IDs out of order
  • Prevent itself from being un-installed from a fork
  • Write to fork storage for a fork its not installed into

Installing an engine

  • The owner of a fork can install an engine to the fork at any time
  • The installed engine can modify token storage for any NFTs that are part of the fork
  • The installed engine determines appearance and royalties for any NFTs that part of the fork
  • The installed engine can write to the fork-specific storage at any time
  • An engine is informed anytime it’s installed to a fork.
    • The engine has the opportunity to prevent installation by reverting in this hook