Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions website/docs/contribution/code-style-guide.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
sidebar_position: 3
title: Code Style Guide
description: Code style guidelines for developing Compose facets and libraries
description: Code style guidelines for developing Compose facets and modules
---

This section outlines the code style guidelines for developing new facets and Solidity libraries in **Compose**.
This section outlines the code style guidelines for developing new facets and Solidity modules in **Compose**.

Follow [Compose's design principles](/docs/design) when contributing code.

Expand All @@ -19,11 +19,11 @@ Follow the [Solidity feature ban](/docs/design/banned-solidity-features).
error ERC20InvalidSender(address _sender);
function transfer(address _to, uint256 _amount) external {}
```
- **Camel Case:** Use camelCase for variable, function, contract, and library names, except for standard uppercase abbreviations (e.g., ERC).
- Example: `totalSupply`, `LibERC20`, `ERC721Facet`
- **Camel Case:** Use camelCase for variable, function, contract, and module names, except for standard uppercase abbreviations (e.g., ERC).
- Example: `totalSupply`, `ERC20Mod`, `ERC721Facet`

- **Facets:** Internal function names in facets should be prefixed with `internal` if they otherwise have the same name as an external function in the same facet. Usually, there should be few or no internal functions in facets; repeat code if it improves readability.
- **Libraries:** All functions in libraries use the `internal` visibility specifier.
- **Modules:** All functions in modules use the `internal` visibility specifier.

### Value Resetting
- Use `delete` to set a value to zero.
Expand Down
12 changes: 6 additions & 6 deletions website/docs/design/banned-solidity-features.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
sidebar_position: 4
title: Banned Solidity Features
description: Solidity language features that are banned from Compose facets and libraries.
description: Solidity language features that are banned from Compose facets and modules.
---

The following Solidity language features are **banned** from Compose facets and libraries.
The following Solidity language features are **banned** from Compose facets and modules.

Compose restricts certain Solidity features to keep facet and library code **simpler**, **more consistent**, and **easier to reason about**.

Expand Down Expand Up @@ -96,7 +96,7 @@ function approve(address _spender, uint256 _value) public {

<Accordion title="No external functions in Solidity libraries">

All Solidity library functions must be declared `internal`.
All Solidity module functions must be declared `internal`.

```solidity title="🚫 Not allowed"
function transfer() external {
Expand All @@ -106,10 +106,10 @@ function transfer() external {

</Accordion>

<Accordion title="No `using` directives in libraries">
<Accordion title="No `using` directives in modules">

```solidity title="🚫 Not allowed"
using LibSomething for uint256;
using SomethingMod for uint256;
```

</Accordion>
Expand Down Expand Up @@ -140,7 +140,7 @@ if (x < 10) {

</Accordion>
<Accordion title="No selfdestruct">
No contract or library may use `selfdestruct`
No contract or module may use `selfdestruct`
```solidity title="🚫 Not allowed"
selfdestruct(owner);
```
Expand Down
20 changes: 10 additions & 10 deletions website/docs/design/design-for-composition.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
sidebar_position: 5
title: Design for Composition
description: How to design Compose facets and libraries for composition.
description: How to design Compose facets and modules for composition.
---

Here are the guidelines and rules for creating composable facets.
Expand All @@ -20,17 +20,17 @@ We focus on building **small, independent, and easy-to-read facets**. Each facet
6. Facets are fully self-contained. They do not import anything.


## Writing Facet Libraries
## Writing Facet Modules

1. Facet libraries are self-contained code units. They do not import anything.
2. Each facet should have one corresponding facet library.
3. Facet libraries are used to initialize facets on deployment and during upgrades.
4. Facet libraries are also used to integrate custom facets with Compose facets.
5. Facet libraries have one or more functions which are used to initialize storage variables during deployment.
1. Facet modules are self-contained code units. They do not import anything.
2. Each facet should have one corresponding facet modules.
3. Facet modules are used to initialize facets on deployment and during upgrades.
4. Facet modules are also used to integrate custom facets with Compose facets.
5. Facet modules have one or more functions which are used to initialize storage variables during deployment.

## Facets & Libraries
## Facets & Modules

1. Facets and facet libraries should not contain owner/admin authorization checks unless absolutely required or fundamental to the functionality being implemented. If permission or authorization checks are required, the facet should integrate with `OwnerFacet` or `AccessControlFacet`.
1. Facets and facet modules should not contain owner/admin authorization checks unless absolutely required or fundamental to the functionality being implemented. If permission or authorization checks are required, the facet should integrate with `OwnerFacet` or `AccessControlFacet`.


## Extending Facets
Expand All @@ -47,7 +47,7 @@ We focus on building **small, independent, and easy-to-read facets**. Each facet
9. Never add new variables to an existing struct.

:::info Important
Maintain the same order of variables in structs when reusing them across facets or libraries. Unused variables may only be removed from the end of a struct.
Maintain the same order of variables in structs when reusing them across facets or modules. Unused variables may only be removed from the end of a struct.
:::


Expand Down
6 changes: 3 additions & 3 deletions website/docs/design/written-to-be-read.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,21 @@ This is the top design and guiding principle of this project. We help our users

The design of Compose includes guidelines and rules that promote readability and consistency throughout the codebase.

Though many people may contribute to the Compose standard library of facets and libraries, it should look like it was written by one person.
Though many people may contribute to the Compose standard library of facets and modules, it should look like it was written by one person.

***

### Facets Are Self-Contained

Each facet is a complete, standalone unit. Its source file contains all the code it needs, with no imports or dependencies on other files.

Likewise, each Solidity library is also self-contained, with no external imports or dependencies.
Likewise, each Solidity module is also self-contained, with no external imports or dependencies.

***

### Facets Are Read from Top to Bottom

Compose facets and libraries are written to be read naturally from top to bottom.
Compose facets and modules are written to be read naturally from top to bottom.

Definitions appear before their use, so readers don't need to jump around the file to understand the code.

24 changes: 12 additions & 12 deletions website/docs/facets/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ The `AccessControlFacet` provides standard role-based access control functionali
Here's how to integrate access control in your custom facet:

```solidity
import {LibAccessControl} from "compose/LibAccessControl.sol";
import {AccessControlMod} from "compose/AccessControlMod.sol";

contract AdminFacet {
// Define your custom role
Expand Down Expand Up @@ -163,30 +163,30 @@ bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");

## Integration with Custom Facets

Your custom facets can use `LibAccessControl` to check permissions:
Your custom facets can use `AccessControlMod` to check permissions:

```solidity
import {LibAccessControl} from "compose/LibAccessControl.sol";
import {LibERC20} from "compose/LibERC20.sol";
import {AccessControlMod} from "compose/AccessControlMod.sol";
import {ERC20Mod} from "compose/ERC20Mod.sol";

contract TokenMinterFacet {
bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");

function mintTokens(address to, uint256 amount) external {
// Check minter permission
require(
LibAccessControl.hasRole(MINTER_ROLE, msg.sender),
AccessControlMod.hasRole(MINTER_ROLE, msg.sender),
"TokenMinter: caller is not minter"
);

// Mint using Compose's ERC20 library
LibERC20.mint(to, amount);
ERC20Mod.mint(to, amount);
}
}
```

<Callout type="success" title="Shared Storage Power">
The `LibAccessControl` library accesses the same storage as `AccessControlFacet`, so permissions set through the facet are instantly available to your custom facets!
The `AccessControlMod` library accesses the same storage as `AccessControlFacet`, so permissions set through the facet are instantly available to your custom facets!
</Callout>

## Security Considerations
Expand Down Expand Up @@ -226,17 +226,17 @@ contract TimeLockFacet {
uint256 duration
) external {
require(
LibAccessControl.hasRole(DEFAULT_ADMIN_ROLE, msg.sender),
AccessControlMod.hasRole(DEFAULT_ADMIN_ROLE, msg.sender),
"Not admin"
);

LibAccessControl.grantRole(OPERATOR_ROLE, account);
AccessControlMod.grantRole(OPERATOR_ROLE, account);
roleExpiry[account] = block.timestamp + duration;
}

function revokeExpiredRoles(address account) external {
if (block.timestamp >= roleExpiry[account]) {
LibAccessControl.revokeRole(OPERATOR_ROLE, account);
AccessControlMod.revokeRole(OPERATOR_ROLE, account);
}
}
}
Expand All @@ -247,9 +247,9 @@ contract TimeLockFacet {
<FeatureGrid columns={2}>
<FeatureGridItem
icon={<Icon name="diamond" size={32} />}
title="Facets & Libraries"
title="Facets & Modules"
description="Learn how authentication integrates with the facet architecture."
href="/docs/foundations/facets-and-libraries"
href="/docs/foundations/facets-and-modules"
/>
<FeatureGridItem
icon={<Icon name="shield" size={32} />}
Expand Down
Loading