Living architecture documentation

See Domain model to understand the various entities of the protocol.

System Level Architecture

  • A Factory contract (ShellFactory.sol) can deploy clones (OZ minimal immutable proxy pattern) of various NFT collection types
    • The factory has an owner that can add new collection implementations
  • An Implementation contract is a NFT collection that implements the shell framework. Each implementation is registered with the factory by an arbitrary name (eg, shell-erc721-v1).
    • Only the factory owner can register a new implementation
    • Implementations are immutable, once registered, they cannot be changed or removed.
    • All implementations must implement IShellFramework.sol
    • Implementations can implement any NFT token spec (ERC-721 or ERC-1155)
      • See ShellERC721.sol, ShellERC1155.sol, etc
    • Implementations cannot be used directly, they are the source of all cloned collections.
  • Anybody may permissionlessly deploy a Collection, which is a minimal proxy clone of a registered implementation
    • Each collection is a fully independent and sovereign NFT contract
    • Collections may be either ERC-721 or ERC-1155, depending on the implementation
    • Collections contain various forks, each of which has an owner that can hot-swap the installed engine for that fork at any time
  • An Engine is a standalone smart contract that implements IEngine.sol
    • A collection will delegate metadata resolution (tokenURI or uri methods) and royalty computation (ERC-2981) to the currently installed engine
    • The currently installed engine can store data associated with the collection, or a specific NFT, in a portable key-value store that persists across engine hot-swaps