diff --git a/README.md b/README.md index 7c67b217..49925fc2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Compose +# Compose +![Coverage](https://img.shields.io/badge/coverage-63%25-yellow) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Discord](https://img.shields.io/badge/Discord-Join%20Chat-blue.svg)](https://discord.gg/DCBD2UKbxc) > **⚠️ Early Stage**: Compose is currently in development and only available to contributors. It is **NOT production ready**. @@ -14,14 +15,12 @@ Compose is a smart contract library that helps developers create smart contract The project actively evolves based on community input—[tell us](https://github.com/Perfect-Abstractions/Compose/discussions/108) what you'd like Compose to do for you. -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) -[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-blue.svg)](https://discord.gg/DCBD2UKbxc) ## Why Compose is Different **Forget traditional smart contract design patterns**—Compose takes a radically different approach. -We build high-quality smart contracts by **intentionally restricting Solidity features** and following conventions designed specifically for smart contracts. This is **Smart Contract Oriented Programming (SCOP)**. +We build high-quality smart contracts by **intentionally restricting Solidity features** and following conventions designed specifically for smart contracts. This is **Smart Contract Oriented Programming (SCOP)**. ### Core Philosophy diff --git a/lib/forge-std b/lib/forge-std index 100b0d75..8e40513d 160000 --- a/lib/forge-std +++ b/lib/forge-std @@ -1 +1 @@ -Subproject commit 100b0d756adda67bc70aab816fa5a1a95dcf78b6 +Subproject commit 8e40513d678f392f398620b3ef2b418648b33e89 diff --git a/website/docs/_introOld.mdx b/website/docs/_introOld.mdx deleted file mode 100644 index 531a11a0..00000000 --- a/website/docs/_introOld.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -sidebar_position: 2 -slug: / -title: "Introduction Another" ---- - -import DocHero from '@site/src/components/docs/DocHero'; -import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; -import Callout from '@site/src/components/ui/Callout'; -import FeatureGrid, { FeatureGridItem } from '@site/src/components/features/FeatureGrid'; - - - - -## Foundations - -

- The building blocks of the Compose platform. -

- - - } - href="/docs/foundations/authentication" - /> - } - href="/docs/foundations/facets-and-libraries" - /> - } - href="/docs/" - /> - } - href="/docs/" - /> - - - -Compose is currently in development and only available to contributors. It is **NOT production ready**. Use at your own risk in development environments only. - - -## What is Compose? - -**Compose** is a revolutionary smart contract library that helps developers create sophisticated smart contract systems using the **ERC-2535 Diamond** standard. It's designed from the ground up to prioritize code readability, on-chain composability, and developer understanding. - -### The Vision - -Imagine having access to a comprehensive, verified standard library of smart contract components that you can combine like LEGO blocks to build complex systems—all deployed once on-chain and reused across your projects. That's Compose. - -## Key Features - - - } - title="On-Chain Standard Library" - description="Access verified, audited facets deployed once and reused across multiple diamonds on multiple blockchains." - /> - } - title="Composable Architecture" - description="Mix and match facets and libraries to build exactly what you need without inheritance conflicts." - /> - } - title="Readability First" - description="Code designed to be understood. Smart Contract Oriented Programming prioritizes clarity over cleverness." - /> - } - title="Upgradeable by Design" - description="Full power of ERC-2535 Diamonds means your contracts can evolve without redeployment." - /> - } - title="Battle-Tested Patterns" - description="Community-reviewed implementations following proven best practices and security standards." - /> - } - title="Developer Experience" - description="Intuitive APIs, comprehensive documentation, and helpful libraries make development a breeze." - /> - - -## How It Works - -Compose uses a **shared storage architecture** where both standard facets and your custom facets access the same data: - -```solidity -// Your custom facet integrates with Compose using libraries -import {LibERC721} from "compose/LibERC721.sol"; - -contract GameNFTFacet { - function mintWithGameLogic(address player, uint256 tokenId) external { - // Your custom game logic - require(playerHasEnoughPoints(player), "Not enough points"); - - // Use LibERC721 to mint - this modifies the SAME storage - // that ERC721Facet uses for balanceOf(), ownerOf(), etc. - LibERC721.mint(player, tokenId); - - // Now the player owns this NFT and can use standard - // ERC721Facet.transferFrom() to transfer it! - updatePlayerStats(player); - } -} -``` - - -Both your `GameNFTFacet` and the standard `ERC721Facet` work with the **same storage** in your diamond. This is the power of Compose's shared storage architecture. - - -## Why Choose Compose? - -### Our value -- **Readability**: Code that's easy to understand and audit -- **Reusability**: Deploy once, use everywhere -- **Standards**: Battle-tested, community-reviewed implementations -- **Upgradability**: Full power of ERC-2535 Diamonds -- **Composability**: Mix and match functionality without conflicts - -### Perfect For: -- Building complex DeFi protocols -- Creating NFT platforms with custom logic -- Developing DAO governance systems -- Projects requiring upgradeable smart contracts -- Teams that prioritize code quality and maintainability - -## Core Principles - - - } - title="Read First" - description="Code clarity is the top priority. Every line should be understandable by developers and auditors." - /> - } - title="Diamond-Native" - description="Designed specifically for ERC-2535. Not adapted from inheritance patterns." - /> - } - title="Composition Over Inheritance" - description="Combine facets instead of inheriting. Avoid the complexity of inheritance hierarchies." - /> - } - title="Intentional Simplicity" - description="Banned features lead to clearer code. Less magic, more understanding." - /> - - -## Next Steps - - - } - href="/docs/getting-started/installation" - size="large" - /> - } - href="/docs/getting-started/quick-start" - size="large" - /> - - -## Community & Support - -Compose is built with 🩵 by a vibrant community of developers who care about code quality. - - - } - href="https://discord.gg/compose" - external={true} - size="small" - /> - } - href="https://github.com/Perfect-Abstractions/Compose/discussions" - external={true} - size="small" - /> - } - href="https://github.com/Perfect-Abstractions/Compose" - external={true} - size="small" - /> - } - href="/blog" - size="small" - /> - - ---- - -
-Ready to revolutionize your smart contract development? Let's get started! 🚀 -
- diff --git a/website/docs/design/design-for-composition.mdx b/website/docs/design/design-for-composition.mdx index c36c9972..5754457b 100644 --- a/website/docs/design/design-for-composition.mdx +++ b/website/docs/design/design-for-composition.mdx @@ -6,7 +6,7 @@ description: How to design Compose facets and libraries for composition. Here are guidelines and rules to create composable facets. -Compose replaces source-code inheritance with onchain composition. Facets are the building blocks; diamonds wire them together. +Compose replaces source-code inheritance with on-chain composition. Facets are the building blocks; diamonds wire them together. We focus on building **small, independent, and easy-to-read facets**. Each facet is deployed once, then reused and combined with other facets to form complete, modular smart contract systems. @@ -63,4 +63,4 @@ For example, `ERC721EnumerableFacet` does not extend `ERC721Facet` because enume *** -This level of composability strikes the right balance: it enables highly organized, modular, and understandable onchain smart contract systems. +This level of composability strikes the right balance: it enables highly organized, modular, and understandable on-chain smart contract systems. diff --git a/website/docs/design/index.mdx b/website/docs/design/index.mdx index 630e99b8..7018fd16 100644 --- a/website/docs/design/index.mdx +++ b/website/docs/design/index.mdx @@ -5,18 +5,53 @@ description: Overview for how Compose is designed sidebar_class_name: hidden --- -This section contains the guidelines and rules for developing new facets and Solidity libraries in **Compose**. - -We focus on building small, independent, and easy-to-understand facets. Each facet is designed to be deployed once, then reused and composed seamlessly with others to form complete smart contract systems. +import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; +import DocSubtitle from '@site/src/components/docs/DocSubtitle'; + +This section contains the guidelines and rules for developing new facets and Solidity libraries in **Compose**. We focus on building small, independent, and easy-to-understand facets. Each facet is designed to be deployed once, then reused and composed seamlessly with others to form complete smart contract systems. + ## Articles in this section -- [Compose Is Written to Be Read](./written-to-be-read) — Emphasizes clarity first: keep facets and libraries self-contained, ordered top-to-bottom, and easy to read. Avoid clever abstractions that reduce readability. - -- [Repeat Yourself](./repeat-yourself) — Prefer duplication over indirection when it improves clarity. - -- [Banned Solidity Features](./banned-solidity-features) — Solidity Features we don't use in facets/libraries. - -- [Design for Composition](./design-for-composition) — Facets replace inheritance with onchain composition. Keep facets small and self-contained, pair each facet with a library, reuse storage layouts carefully, and extend behavior by adding new facets. + + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + -- [Maintain Compatibility](./maintain-compatibility) — Build facets that work with existing standards, libraries, and systems and exhibit expected behavior. +:::warning[Early Development] +Compose is still in early development and currently available only to contributors. +It is not **production-ready** — use it in test or development environments only. +::: \ No newline at end of file diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx new file mode 100644 index 00000000..2143a133 --- /dev/null +++ b/website/docs/foundations/composable-facets.mdx @@ -0,0 +1,93 @@ +--- +sidebar_position: 5 +title: Composable Facets +description: Mix and match facets to build complex systems from simple, interoperable building blocks. +--- + +The word **"composable"** means *able to be combined with other parts to form a whole*. + +In **Compose**, facets are designed to be **composable**. They're built to interoperate seamlessly with other facets inside the same diamond. + +Composable design makes it possible to **mix, match, and extend** smart contract functionality across diverse use cases — without modifying or redeploying source code. It turns smart contracts into reusable building blocks. + +## What Makes Facets Composable? + +Smart Contract Composability isn't automatic. Compose facets are designed with specific patterns that enable seamless interaction: + +### 1. **Shared Storage Patterns** +Facets use the **Diamond Storage** (`ERC-8042`) to avoid storage collisions. Each facet manages its own isolated storage namespace while being able to read shared state when needed. + +### 2. **Standard Interfaces** +Facets expose predictable, standard-compliant function signatures (`ERC-20`, `ERC-721`, etc.) that work together naturally. + +### 3. **Minimal Dependencies** +Each facet is self-contained but cooperative. They don't assume what other facets are present, but can enhance functionality when compatible facets are detected. + +### 4. **Modular Functionality** +Complex features are broken into focused facets. Want pausability? Add `PausableFacet`. Need access control? Add `AccessControlFacet`. + +## Composition in Action + +### Example 1: Basic to Advanced Token + +Start simple, add features as needed: + +```solidity +// Launch Day +Diamond MyToken { + ERC20Facet // Basic token functionality +} +``` + +Each addition requires zero changes to existing facets. + +### Example 2: Access Control + Pausable Token + +Facets can depend on and enhance each other: + +```solidity +Diamond GovernedToken { + ERC20Facet // Basic token + AccessControlFacet // Role-based permissions + ERC20PausableFacet // Pause functionality +} +``` + +Here's how they compose: +- `ERC20PausableFacet` checks `AccessControlFacet` to verify the caller has the `PAUSER_ROLE` +- `ERC20Facet` checks `ERC20PausableFacet` state to prevent transfers when paused +- Each facet remains independent but works together seamlessly + +### Example 3: NFT with Royalties and Metadata + +```solidity +Diamond ArtCollection { + ERC721Facet // Core NFT functionality + ERC721MetadataFacet // Token URI and metadata + ERC721RoyaltyFacet // EIP-2981 royalty info + ERC721EnumerableFacet // Token enumeration + AccessControlFacet // Minter role management +} +``` + +:::tip[Key Insight] +On-chain facets are the **building blocks** of Compose. Like LEGO bricks, they're designed to snap together in different configurations to build exactly what you need. +::: + +## Composability Benefits + +1. **Start Simple, then Scale**: Begin with core functionality, add features over time +3. **Reduce Testing Burden**: Use pre-tested facets from the Compose library to build your project +4. **Architectural Flexibility**: Same facets, infinite configurations based on your project needs + +### Composition vs. Inheritance + +Traditional smart contracts use **inheritance** to combine functionality: +- Requires recompilation when features change +- Creates large, monolithic contracts +- Creates code duplication of the same base functionality across multiple projects + +Compose uses **composition** via facets: +- No recompilation needed to add/remove features +- Small, focused contracts that work together +- Same facets work across unlimited projects diff --git a/website/docs/foundations/composable-smart-contracts.mdx b/website/docs/foundations/composable-smart-contracts.mdx deleted file mode 100644 index 3de2c1b7..00000000 --- a/website/docs/foundations/composable-smart-contracts.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 5 -title: Composable Smart Contracts -description: Compose smart contracts are designed to be composable. ---- - -The word **"composable"** means *able to be combined with other parts to form a whole*. - -In **Compose**, facets are designed to be **composable** — they're built to interoperate seamlessly with other facets inside the same diamond. - -Composable design makes it possible to **mix, match, and reuse** smart contract logic across many projects — without modifying or redeploying source code. It turns smart contracts into reusable building blocks. - -:::tip[Key Insight] -Onchain facets are the **building blocks** of Compose. -::: - -**Examples of composition:** -1. `ERC20Facet`, `ERC20PermitFacet` and `ERC20BridgableFacet`can be combined in a single diamond to create a fully featured ERC-20 token. -2. Facets `ERC721Facet`, `ERC721MetadataFacet`, `ERC721RoyaltyFacet` can be composed to build an ERC-721 NFT contract. - -### Why This Matters - -Traditional smart contract libraries extend functionality through **inheritance at the source-code level**, for example: - -```Solidity -contract ERC20Permit is ERC20 { ... } -``` - -This approach tightly couples code and forces every variant to be redeployed as a new contract. - -**Compose changes that.** - -Instead of inheritance, it uses **onchain composition** — combining existing deployed facets inside a diamond. - -This reduces duplication, improves upgradeability, and makes smart contract systems more flexible and maintainable. \ No newline at end of file diff --git a/website/docs/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index 7f623f6d..a5d0428b 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -1,17 +1,17 @@ --- -sidebar_position: 6 +sidebar_position: 7 title: "Custom Functionality: Compose Your Own Facets" -description: Compose smart contracts are designed to be composable. +description: "Build your own facets that work seamlessly with existing Compose Functionality." --- Many projects need custom functionality beyond the standard facets. Compose is designed for this — you can build and integrate your own facets that work seamlessly alongside existing Compose facets. -Compose provides Solidity libraries that expose the same storage layouts and internal logic used by its onchain facets. This lets your custom facets share data and interact directly with Compose's reusable facets. +Compose provides Solidity libraries that expose the same storage layouts and internal logic used by its on-chain facets. This lets your custom facets share data and interact directly with Compose's reusable facets. **Example: Adding Game Logic to ERC-721** -Suppose you're building an onchain game and want to include the `ERC721Facet` in your diamond. +Suppose you're building an on-chain game and want to include the `ERC721Facet` in your diamond. You can add your own `GameNFTFacet` that extends functionality while still sharing the same ERC-721 storage through `LibERC721`: ```Solidity diff --git a/website/docs/foundations/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index fd12a363..ee6650c5 100644 --- a/website/docs/foundations/diamond-contracts.mdx +++ b/website/docs/foundations/diamond-contracts.mdx @@ -1,20 +1,20 @@ --- sidebar_position: 1 -title: Diamond Smart Contracts +title: Diamond Contracts description: "Understand Diamonds from the ground up—facets, storage, delegation, and how Compose uses them." --- import DiamondFacetsSVG from '@site/static/img/svg/compose_diamond_facets.svg' -A **diamond contract** is a smart contract that is made up of multiple parts instead of one large block of code. The diamond exists at **one address** and holds **all of the contract's storage**, but it uses separate smart contracts called **facets** to provide its functionality. +A **diamond contract** \(`ERC-2535`\) is a smart contract that is made up of multiple parts instead of one large block of code. The diamond exists at **one address** and holds **all of the contract's storage**, but it uses separate smart contracts called **facets** to provide its functionality. Users interact only with the **diamond**, but the diamond's features come from its **facets**. Each facet provides a small, focused set of functions, and the diamond uses those functions to perform its actions. Because facets can be added, replaced, or removed, a diamond can grow and evolve over time **without changing its address** and without redeploying the entire system. -In simple terms: - -**A diamond contract is one smart contract made from multiple small building blocks (facets), allowing it to be flexible, organized, and able to grow over time.** +:::note[In Simple Terms] +A diamond contract is a smart contract made from multiple small building blocks (facets), allowing it to be flexible, organized, and able to grow over time. +::: A diamond has: - One address diff --git a/website/docs/foundations/facets-and-libraries.mdx b/website/docs/foundations/facets-and-libraries.mdx index 57c03ad2..ac0e16c3 100644 --- a/website/docs/foundations/facets-and-libraries.mdx +++ b/website/docs/foundations/facets-and-libraries.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 6 title: "Understanding Facets and Libraries" description: Learn how facets and libraries work together through shared storage to build composable systems. --- @@ -37,7 +37,7 @@ Compose uses two complementary patterns for smart contract development: **Use a Facet when you want:** - The complete, standard implementation (e.g., full ERC-20 functionality) -- To reuse it (onchain) across multiple diamonds +- To reuse it (on-chain) across multiple diamonds - A verified, audited implementation **Use a Library when you're:** diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index 44d46ea9..210290a0 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -4,22 +4,61 @@ description: Compose smart contracts are designed to be composable. sidebar_class_name: hidden --- -Compose is a new approach to smart contract development that changes how developers build and deploy blockchain applications. This section introduces the core concepts that make Compose unique. +import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; +import DocSubtitle from '@site/src/components/docs/DocSubtitle'; +import Icon from '@site/src/components/ui/Icon'; +import CalloutBox from '@site/src/components/ui/CalloutBox'; -## Articles in this section - -- [Diamond Smart Contracts](./diamond-contracts) — A diamond contract is made up of multiple parts. It exists at one address and holds all storage, but uses separate smart contracts called facets to provide its functionality. - -- [Onchain Smart Contracts](./onchain-smart-contracts) — Compose provides reusable onchain contracts that already exist on blockchains—eliminating the need to deploy or manage them yourself. - -- [Reusable Smart Contracts](./resuable-smart-contracts) — Build new systems from existing onchain contracts through diamond-based architecture. Deploy only a small diamond that connects to existing facets. + + Compose is a new approach to smart contract development that changes how developers build and deploy blockchain applications. This section introduces the core concepts that make Compose unique. + -- [Composable Smart Contracts](./composable-smart-contracts) — Facets interoperate seamlessly inside the same diamond. Mix, match, and reuse logic across projects without modifying or redeploying code. - -- [Custom Functionality: Compose Your Own Facets](./custom-facets) — Build your own facets that work seamlessly with existing Compose facets using shared storage layouts and internal logic through Solidity libraries. - -- [Understanding Facets and Libraries](./facets-and-libraries) — Learn how facets and libraries work together through shared storage to build composable systems. +## Articles in this section + + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + } + size="medium" + /> + :::warning[Early Development] Compose is still in early development and currently available only to contributors. diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx new file mode 100644 index 00000000..668420f9 --- /dev/null +++ b/website/docs/foundations/onchain-contract-library.mdx @@ -0,0 +1,41 @@ +--- +sidebar_position: 3 +title: On-chain Library +description: Compose provides a set of reusable on-chain contracts that already exist on blockchains +--- + +import DocSubtitle from '@site/src/components/docs/DocSubtitle'; + + +**Compose takes a different approach.** + +Compose provides a set of **reusable on-chain contracts** that already exist on blockchains. You don't need to deploy or manage them yourself. The heavy lifting has been done for you. + + +## Why This Matters + +Traditionally, you would extend functionality through **inheritance at the source-code level**, for example: + +```Solidity +contract ERC20Permit is ERC20 { ... } +``` + +This approach tightly couples code and forces every variant to be redeployed as a new contract, resulting in the same code being duplicated and deployed across countless projects. + +**Compose changes that!** + +Instead of inheritance, it uses **on-chain composition** — combining existing deployed facets and your own custom facets inside a single diamond. + +This reduces duplication, improves upgradeability, and makes smart contract systems more flexible and maintainable. + +For your next project, instead of deploying new contracts, simply **use the existing on-chain contracts** provided by Compose. + + +:::tip[Key Insight] +Compose is a general purpose **on-chain** smart contract library. +::: + +:::info[In Development] +Compose is still in early development, and its smart contracts haven't been deployed yet. +We're actively building—and if this vision excites you, we'd love for you to join us. +::: diff --git a/website/docs/foundations/onchain-smart-contracts.mdx b/website/docs/foundations/onchain-smart-contracts.mdx deleted file mode 100644 index de617c3b..00000000 --- a/website/docs/foundations/onchain-smart-contracts.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 3 -title: Onchain Smart Contracts -description: Compose provides a set of reusable on-chain contracts that already exist on blockchains ---- - -Traditional smart contract libraries give you source code that you must modify, extend, and deploy yourself to one or more blockchains. - -**Compose takes a different approach.** - -Compose provides a set of **reusable onchain contracts** that already exist on blockchains—you don't need to deploy or manage them yourself. The heavy lifting has been done. - -For your next project, instead of deploying new contracts, simply **use the existing onchain contracts** provided by Compose. - - -:::tip[Key Insight] -Compose is a general purpose **onchain** smart contract library. -::: - -:::info[In Development] -Compose is still in early development, and its smart contracts haven't been deployed yet. -We're actively building—and if this vision excites you, we'd love for you to join us. -::: diff --git a/website/docs/foundations/resuable-smart-contracts.mdx b/website/docs/foundations/resuable-smart-contracts.mdx deleted file mode 100644 index 9e83e811..00000000 --- a/website/docs/foundations/resuable-smart-contracts.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 4 -title: Reusable Smart Contracts -description: Compose smart contracts are reusable onchain facets ---- - -import DiamondFacetsSVG from '@site/static/img/svg/compose_diamond_facets.svg' - -You might be wondering: **How can I create a new project without deploying new smart contracts?** - -How does Compose make it possible to build new systems from existing onchain contracts? - -The answer lies in Compose's smart contract architecture, which is based on [diamond contracts](/docs/foundations/diamond-contracts). - -A diamond contract is a simple, tiny contract that **uses the code of other onchain contracts** called **facets**. Each diamond uses the code of other contracts (facets) to create and maintain its storage data. - -When you use Compose, you *do* deploy new contracts—but only the small diamond contract that ties together existing onchain facets. - -Let's look at a simple example. - -Suppose you want to create a new ERC-20 token that supports gasless approvals (permit) and cross-chain bridging. - -With Compose, you can: - -1. **Select the facets you need** – for example, `ERC20Facet`, `ERC20PermitFacet`, and `ERC20BridgableFacet`. -2. **Provide initialization data** – such as the token name, symbol, and total supply. -3. **Deploy your diamond** – which initializes your ERC-20 token and connects it to the chosen facets. - -:::tip[Key Insight] -Many diamond contracts can be deployed that **reuse the same onchain facets**. -::: \ No newline at end of file diff --git a/website/docs/foundations/reusable-facet-logic.mdx b/website/docs/foundations/reusable-facet-logic.mdx new file mode 100644 index 00000000..05a6d62f --- /dev/null +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -0,0 +1,60 @@ +--- +sidebar_position: 4 +title: Reusable Logic +description: Deploy once, reuse everywhere. Compose facets are shared across thousands of projects. +--- + +import DiamondFacetsSVG from '@site/static/img/svg/compose_diamond_facets.svg' + +You might be wondering: **How can I create a new project without deploying new smart contracts?** + +The answer lies in Compose's smart contract architecture, which is based on [diamond contracts](/docs/foundations/diamond-contracts). + +## Understanding Reusability + +A diamond contract is a simple, small proxy contract that **delegates to the code of other on-chain contracts** called **facets**. Each diamond uses the code of other contracts (facets) to execute logic and maintain its storage data. + +When you use Compose, you *do* deploy a new contract, this small contract is called a **diamond** + +## What You're NOT Deploying + +When you create a new diamond, you avoid redeploying: + +- The core token logic with the `ERC20Facet` +- The permit functionality with the `ERC20PermitFacet` +- The bridging code with the `ERC20BridgableFacet` + +Instead, you deploy: + +- A lightweight diamond contract +- Your unique initialization data (`name`, `symbol`, `supply`) +- Configuration linking to existing facet addresses + +## Example + +Suppose you want to create a new ERC-20 token that supports gasless approvals (permit) and cross-chain bridging. + +With Compose, you: + +1. **Select existing facets**: `ERC20Facet`, `ERC20PermitFacet`, and `ERC20BridgableFacet` are already deployed on-chain +2. **Provide initialization data**: your token's name, symbol, and total supply +3. **Deploy your diamond**: a small proxy contract that references the facet addresses and logic + +## The Power of Reusability + +**One facet, thousands of projects:** + +If 1,000 projects use the same `ERC20Facet`: +- That's **999 deployments saved** +- **Millions in gas costs avoided** +- **1,000 projects** benefit from the same audited, battle-tested code + +:::tip[Key Insight] +Many diamond contracts can be deployed that **reuse the same on-chain facets**. Each diamond manage its own storage and state, but shares the execution code with all other diamonds using the same facets. +::: + +## Benefits of Reusable Facets + +1. **Lower Deployment Costs**: Deploy only a small proxy instead of thousands of lines of logic +2. **Shared Security Audits**: When a facet is audited, all diamonds using it benefit +3. **Consistent Behavior**: Same code means same behavior across all implementations \ No newline at end of file diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index cf83c75e..6fae0680 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -5,49 +5,37 @@ title: "Introduction" description: Compose is a smart contract library for building modular, upgradeable systems using the ERC-2535 Diamond standard. --- -import DocHero from '@site/src/components/docs/DocHero'; +import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; import Callout from '@site/src/components/ui/Callout'; import FeatureGrid, { FeatureGridItem } from '@site/src/components/features/FeatureGrid'; -{/* - -*/} + +**Compose** is a smart contract library that helps developers build modular, upgradeable systems using the [ERC-2535 Diamond](https://eips.ethereum.org/EIPS/eip-2535) standard. It's designed from the ground up for **code clarity**, **reusability**, and **on-chain composability**. + -{/* **Compose** is a general-purpose smart contract library that helps you build smart contract systems. */} +## The Vision - -**Compose** is a smart contract library that helps developers build modular, upgradeable systems using the [ERC-2535 Diamond](https://eips.ethereum.org/EIPS/eip-2535) standard. - -It's designed from the ground up for **code clarity**, **reusability**, and **onchain composability**. - -### The Vision - -Imagine a verified, standard library of **onchain smart contract components** — +Imagine a verified, standard library of **on-chain smart contract components** — each one small, self-contained, and reusable like LEGO blocks. Deployed once, trusted by all, and combined in endless ways to create new systems. -That's **Compose** — where your unique value and functionality connects seamlessly with simple, transparent, onchain building blocks. +That's **Compose** — where your unique value and functionality connects seamlessly with simple, transparent, on-chain building blocks. -## Key Features +## Why Choose Compose? } - title="Onchain Standard Library" + title="On-chain Standard Library" description="(Not yet, in the future) - Access verified, audited smart contracts deployed once and reused across multiple diamonds on multiple blockchains." /> } title="Composable Architecture" - description="Mix and match onchain components to build exactly what you need." + description="Mix and match on-chain components to build exactly what you need." /> } @@ -71,79 +59,53 @@ That's **Compose** — where your unique value and functionality connects seamle /> -## Why Choose Compose? - -### Our value -- **Readability**: Code that's easy to understand and audit -- **Reusability**: Deploy once, then reuse -- **Standards**: Battle-tested, community-reviewed implementations -- **Upgradability**: Full power of ERC-2535 Diamonds -- **Composability**: Mix and match functionality +## Perfect For -### Perfect For: -- Building DeFi protocols -- Creating NFT platforms with custom logic -- Developing DAO governance systems -- Projects requiring upgradeable smart contracts -- Teams that prioritize code quality and maintainability +Our smart contract library is perfect for: +- **DeFi Protocols**: Build financial products with composable, upgradeable components +- **NFT Platforms**: Create custom marketplaces and collections with flexible, reusable logic +- **DAO Governance**: Implement sophisticated voting and proposal systems that can evolve over time +- **Upgradeable Systems**: Any project that needs to adapt and improve without full redeployment +- **Quality-Focused Teams**: Developers who value readable, maintainable, and auditable code -{/* ## Core Principles - - - } - title="Read First" - description="Code clarity is the top priority. Every line should be understandable by developers and auditors." - /> - } - title="Diamond-Native" - description="Designed specifically for ERC-2535. Not adapted from inheritance patterns." - /> - } - title="Composition Over Inheritance" - description="Combine facets instead of inheriting. Avoid the complexity of inheritance hierarchies." - /> - } - title="Intentional Simplicity" - description="Simple code. Less magic, more understanding." - /> - */} -{/* ## Next Steps } - href="/docs/getting-started/installation" + title="Compose Foundations" + description="Learn the foundations of the Compose Library and how it is built." + icon={} + href="/docs/design" size="large" /> } - href="/docs/getting-started/quick-start" + title="Help Us Build Compose" + description="Learn how to contribute to the Compose Library." + icon={} + href="/docs/contribution/how-to-contribute" size="large" /> -*/} -{/* ## Community & Support +## Community & Support -Compose is built with 🩵 by a vibrant community of developers who care about code quality. +Compose is built with 🩵 by a vibrant community of developers who care about their craft. } + icon={} href="https://discord.gg/compose" external={true} size="small" + /> + } + href="/blog" + size="small" /> } + icon={} href="https://github.com/Perfect-Abstractions/Compose" external={true} size="small" /> - } - href="/blog" - size="small" - /> - */} - - - + \ No newline at end of file diff --git a/website/src/pages/home/HomepageHeader.js b/website/src/pages/home/HomepageHeader.js index ed97fc46..71add6ee 100644 --- a/website/src/pages/home/HomepageHeader.js +++ b/website/src/pages/home/HomepageHeader.js @@ -42,7 +42,7 @@ export default function HomepageHeader() { + to="/docs/foundations"> Learn Core Concepts @@ -58,7 +58,7 @@ export default function HomepageHeader() { Join Discord - + Contribute