From e16e9794fc6c302ff682348abe5b38da9cb9ff35 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 17:16:08 -0500 Subject: [PATCH 01/15] add links to readme, update intro --- README.md | 2 +- website/docs/intro.mdx | 94 +++++++++++------------------------------- 2 files changed, 24 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 7c67b217..99ed09eb 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The project actively evolves based on community input—[tell us](https://github **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/website/docs/intro.mdx b/website/docs/intro.mdx index cf83c75e..240a1694 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -5,29 +5,17 @@ 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 on-chain 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**. + -{/* **Compose** is a general-purpose smart contract library that helps you build smart contract systems. */} - - -**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 +## The Vision Imagine a verified, standard library of **onchain smart contract components** — each one small, self-contained, and reusable like LEGO blocks. @@ -36,7 +24,7 @@ Deployed once, trusted by all, and combined in endless ways to create new system That's **Compose** — where your unique value and functionality connects seamlessly with simple, transparent, onchain building blocks. -## Key Features +## Why Choose Compose? -## 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: -- 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 +## Perfect For -{/* ## Core Principles +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 - - } - 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" + 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. - */} - - - + \ No newline at end of file From 0b3328b4cdabe660181d2703b8d8bfa8b026527a Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 17:47:51 -0500 Subject: [PATCH 02/15] improve intro & foundation intro --- website/docs/foundations/index.mdx | 65 ++++++++++++++++++++++++------ website/docs/intro.mdx | 22 +++++----- 2 files changed, 63 insertions(+), 24 deletions(-) diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index 44d46ea9..223a6e5f 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/intro.mdx b/website/docs/intro.mdx index 240a1694..f6ec762b 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -12,7 +12,7 @@ import FeatureGrid, { FeatureGridItem } from '@site/src/components/features/Feat -**Compose** is a smart contract library that helps developers build modular, upgradeable on-chain 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**. +**Compose** is a smart contract library that helps developers build modular, upgradeable onchain 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 @@ -74,7 +74,7 @@ Our smart contract library is perfect for: } + icon={} href="/docs/design" size="large" /> @@ -95,10 +95,17 @@ Compose is built with 🩵 by a vibrant community of developers who care about t } + 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 From d0bbd9f39b57a4e01d005f52f0bcbea700dc5f72 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 17:50:44 -0500 Subject: [PATCH 03/15] switch order --- website/docs/foundations/custom-facets.mdx | 4 ++-- website/docs/foundations/facets-and-libraries.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index 7f623f6d..089acbc4 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -1,7 +1,7 @@ --- -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. diff --git a/website/docs/foundations/facets-and-libraries.mdx b/website/docs/foundations/facets-and-libraries.mdx index 57c03ad2..b6570296 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. --- From d248a62b7b92077e0a227f0e702bd5655cac1a1b Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:13:18 -0500 Subject: [PATCH 04/15] add doc changes --- .../docs/foundations/composable-facets.mdx | 102 ++++++++++++++++++ .../composable-smart-contracts.mdx | 35 ------ .../docs/foundations/diamond-contracts.mdx | 10 +- website/docs/foundations/index.mdx | 2 +- .../foundations/onchain-contract-library.mdx | 41 +++++++ .../foundations/onchain-smart-contracts.mdx | 23 ---- .../foundations/resuable-smart-contracts.mdx | 31 ------ .../docs/foundations/reusable-facet-logic.mdx | 61 +++++++++++ website/docs/intro.mdx | 6 +- website/src/pages/home/HomepageHeader.js | 4 +- 10 files changed, 215 insertions(+), 100 deletions(-) create mode 100644 website/docs/foundations/composable-facets.mdx delete mode 100644 website/docs/foundations/composable-smart-contracts.mdx create mode 100644 website/docs/foundations/onchain-contract-library.mdx delete mode 100644 website/docs/foundations/onchain-smart-contracts.mdx delete mode 100644 website/docs/foundations/resuable-smart-contracts.mdx create mode 100644 website/docs/foundations/reusable-facet-logic.mdx diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx new file mode 100644 index 00000000..bba9b28b --- /dev/null +++ b/website/docs/foundations/composable-facets.mdx @@ -0,0 +1,102 @@ +--- +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 +} + +// Week 2: Add gasless approvals +MyToken.addFacet(ERC20PermitFacet) + +// Month 3: Add cross-chain support +MyToken.addFacet(ERC20BridgableFacet) + +// Month 6: Add governance +MyToken.addFacet(GovernanceFacet) +``` + +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/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index fd12a363..d5addc3e 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/index.mdx b/website/docs/foundations/index.mdx index 223a6e5f..efd2d0f3 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -24,7 +24,7 @@ import CalloutBox from '@site/src/components/ui/CalloutBox'; size="medium" /> } diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx new file mode 100644 index 00000000..0c778bd8 --- /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 onchain 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..ea121a4a --- /dev/null +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -0,0 +1,61 @@ +--- +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 +4. **Instant Upgrades**: Bug fixes and improvements to facets benefit all users immediately (when upgradeable) \ No newline at end of file diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index f6ec762b..51670410 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -12,12 +12,12 @@ import FeatureGrid, { FeatureGridItem } from '@site/src/components/features/Feat -**Compose** is a smart contract library that helps developers build modular, upgradeable onchain 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**. +**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**. ## 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. @@ -29,7 +29,7 @@ That's **Compose** — where your unique value and functionality connects seamle } - 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." /> + to="/docs/foundations"> Learn Core Concepts @@ -58,7 +58,7 @@ export default function HomepageHeader() { Join Discord - + Contribute From 05e481f0b9a725f84d0e9eaa85b34aefbec48d51 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:21:10 -0500 Subject: [PATCH 05/15] improve design index --- lib/forge-std | 2 +- website/docs/design/index.mdx | 57 ++++++++++++++++++++++++++++------- 2 files changed, 47 insertions(+), 12 deletions(-) diff --git a/lib/forge-std b/lib/forge-std index 100b0d75..b8f065fd 160000 --- a/lib/forge-std +++ b/lib/forge-std @@ -1 +1 @@ -Subproject commit 100b0d756adda67bc70aab816fa5a1a95dcf78b6 +Subproject commit b8f065fda83b8cd94a6b2fec8fcd911dc3b444fd 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 From 008e11041608a1cd90265a75feb40a01ae3993aa Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:37:10 -0500 Subject: [PATCH 06/15] add coverage badge to readme --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 99ed09eb..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,8 +15,6 @@ 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 From d1a65cfbb99b08538f6eb6b3aadb489ac0bbfd9e Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:40:16 -0500 Subject: [PATCH 07/15] fix broken link --- website/docs/foundations/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index efd2d0f3..f0458404 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -26,21 +26,21 @@ import CalloutBox from '@site/src/components/ui/CalloutBox'; } size="medium" /> } size="medium" /> } size="medium" /> From 56dd7f728d177ce6e53ca06a6e365cd17e048556 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:56:06 -0500 Subject: [PATCH 08/15] remove bold --- website/docs/foundations/diamond-contracts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/foundations/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index d5addc3e..ee6650c5 100644 --- a/website/docs/foundations/diamond-contracts.mdx +++ b/website/docs/foundations/diamond-contracts.mdx @@ -13,7 +13,7 @@ Users interact only with the **diamond**, but the diamond's features come from i 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. :::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 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: From 0b3de8b9015de5561a0a88f230a68d778655f964 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:58:20 -0500 Subject: [PATCH 09/15] remove last benefit --- website/docs/foundations/reusable-facet-logic.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/foundations/reusable-facet-logic.mdx b/website/docs/foundations/reusable-facet-logic.mdx index ea121a4a..05a6d62f 100644 --- a/website/docs/foundations/reusable-facet-logic.mdx +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -57,5 +57,4 @@ Many diamond contracts can be deployed that **reuse the same on-chain 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 -4. **Instant Upgrades**: Bug fixes and improvements to facets benefit all users immediately (when upgradeable) \ No newline at end of file +3. **Consistent Behavior**: Same code means same behavior across all implementations \ No newline at end of file From 4ef573badd3c7738005d09203eb4120b469fd4bb Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 20:59:40 -0500 Subject: [PATCH 10/15] fix heading --- website/docs/foundations/composable-facets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx index bba9b28b..9a2af797 100644 --- a/website/docs/foundations/composable-facets.mdx +++ b/website/docs/foundations/composable-facets.mdx @@ -89,7 +89,7 @@ On-chain facets are the **building blocks** of Compose. Like LEGO bricks, they'r 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 +### Composition vs. Inheritance Traditional smart contracts use **inheritance** to combine functionality: - Requires recompilation when features change From adf9f613af90436776b2f1fee3d42ea47c23a9e4 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 21:03:25 -0500 Subject: [PATCH 11/15] rename all onchain ref --- website/docs/_introOld.mdx | 231 ------------------ .../docs/design/design-for-composition.mdx | 4 +- website/docs/foundations/custom-facets.mdx | 4 +- .../docs/foundations/facets-and-libraries.mdx | 2 +- website/docs/foundations/index.mdx | 4 +- .../foundations/onchain-contract-library.mdx | 2 +- website/docs/intro.mdx | 4 +- 7 files changed, 10 insertions(+), 241 deletions(-) delete mode 100644 website/docs/_introOld.mdx 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/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index 089acbc4..a5d0428b 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -7,11 +7,11 @@ description: "Build your own facets that work seamlessly with existing Compose F 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/facets-and-libraries.mdx b/website/docs/foundations/facets-and-libraries.mdx index b6570296..ac0e16c3 100644 --- a/website/docs/foundations/facets-and-libraries.mdx +++ b/website/docs/foundations/facets-and-libraries.mdx @@ -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 f0458404..210290a0 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -25,14 +25,14 @@ import CalloutBox from '@site/src/components/ui/CalloutBox'; /> } size="medium" /> } size="medium" diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx index 0c778bd8..668420f9 100644 --- a/website/docs/foundations/onchain-contract-library.mdx +++ b/website/docs/foundations/onchain-contract-library.mdx @@ -28,7 +28,7 @@ Instead of inheritance, it uses **on-chain composition** — combining existing 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 onchain contracts** provided by Compose. +For your next project, instead of deploying new contracts, simply **use the existing on-chain contracts** provided by Compose. :::tip[Key Insight] diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index 51670410..6fae0680 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -22,7 +22,7 @@ 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. ## Why Choose Compose? @@ -35,7 +35,7 @@ That's **Compose** — where your unique value and functionality connects seamle } 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." /> } From 08ffbbf05287552029904828389b19e615fc9140 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 21:08:18 -0500 Subject: [PATCH 12/15] remove code functions in doc --- website/docs/foundations/composable-facets.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx index 9a2af797..2143a133 100644 --- a/website/docs/foundations/composable-facets.mdx +++ b/website/docs/foundations/composable-facets.mdx @@ -37,15 +37,6 @@ Start simple, add features as needed: Diamond MyToken { ERC20Facet // Basic token functionality } - -// Week 2: Add gasless approvals -MyToken.addFacet(ERC20PermitFacet) - -// Month 3: Add cross-chain support -MyToken.addFacet(ERC20BridgableFacet) - -// Month 6: Add governance -MyToken.addFacet(GovernanceFacet) ``` Each addition requires zero changes to existing facets. From cd431969e3462b053f2abeee445c02480fcdaf94 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 21:22:13 -0500 Subject: [PATCH 13/15] remove submodule --- lib/forge-std | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/forge-std b/lib/forge-std index b8f065fd..3f999523 160000 --- a/lib/forge-std +++ b/lib/forge-std @@ -1 +1 @@ -Subproject commit b8f065fda83b8cd94a6b2fec8fcd911dc3b444fd +Subproject commit 3f999523613ab5454a5c4ae4abeaa8ea2ba7bcae From 313497a126416c992b15ae8f0aa9cd35b6671933 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 21:22:22 -0500 Subject: [PATCH 14/15] remove submodule --- lib/forge-std | 1 - 1 file changed, 1 deletion(-) delete mode 160000 lib/forge-std diff --git a/lib/forge-std b/lib/forge-std deleted file mode 160000 index 3f999523..00000000 --- a/lib/forge-std +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 3f999523613ab5454a5c4ae4abeaa8ea2ba7bcae From 39dddffcf21103a7e44f56eab7e0ff488aa645e2 Mon Sep 17 00:00:00 2001 From: Maxime Normandin Date: Tue, 18 Nov 2025 21:30:15 -0500 Subject: [PATCH 15/15] readd forge-std --- lib/forge-std | 1 + 1 file changed, 1 insertion(+) create mode 160000 lib/forge-std diff --git a/lib/forge-std b/lib/forge-std new file mode 160000 index 00000000..8e40513d --- /dev/null +++ b/lib/forge-std @@ -0,0 +1 @@ +Subproject commit 8e40513d678f392f398620b3ef2b418648b33e89