Skip to main content

Understanding Facets and Libraries

Compose uses two complementary patterns for smart contract development:

Facets (Complete Implementations)​

Facets are standalone contracts that contain all the logic needed to implement specific functionality. They're designed to be:

  • Self-contained: All code needed for the feature is in one file
  • Readable top-to-bottom: No jumping between files (or within the same file) to understand the logic
  • Deployed once: Reused across multiple diamonds on-chain
  • Deployed everywhere: Our facets will be deployed on many blockchains at the same addresses

Example: ERC20Facet.sol contains the complete ERC-20 token implementation.

Libraries (Helper Functions)​

Libraries (prefixed with Lib) help developers integrate their custom facets with Compose's facets. They:

  • Provide helper functions: Reusable internal functions for custom facets
  • Access shared storage: Work with the same storage layout as their corresponding facet
  • Enable composition: Allow custom facets to interact with Compose functionality
  • Initializes Deployment: Used to set variables when deploying diamonds

Example: LibERC20.sol provides helper functions to interact with ERC-20 storage from custom facets.

The Key Insight: Shared Storage​

Both facets and libraries access the SAME storage in your diamond. When ERC721Facet and LibERC721 both define identical storage at keccak256("compose.erc721"), they're reading and writing the same data. This is how your custom facets can extend Compose functionality without inheritance.

When to Use Each​

Use a Facet when you want:

  • The complete, standard implementation (e.g., full ERC-20 functionality)
  • To reuse it (onchain) across multiple diamonds
  • A verified, audited implementation

Use a Library when you're:

  • Building a custom facet that needs to interact with Compose features
  • Extending standard functionality with custom logic
  • Initializing storage variables during diamond deployment

Available Facets & Libraries​

Look in the src directory to see the currently provided functionality, facets and libraries.

This site is powered by Netlify