Diamond pattern (EIP-2535) in Blockchain / Solidity - Step-by-Step Execution

Concept Flow - Diamond pattern (EIP-2535)

Start: Deploy Diamond Contract

↓

Add Facets (Modules)

↓

Map Functions to Facets

↓

Call Function

↓

Diamond Delegatecall to Facet

↓

Execute Facet Logic

↓

Return Result

↓

End

The Diamond pattern deploys a main contract (Diamond) that delegates calls to multiple smaller contracts (Facets) based on function selectors.

Execution Sample

Blockchain / Solidity

contract Diamond {
  mapping(bytes4 => address) facets;
  fallback() external {
    address facet = facets[msg.sig];
    (bool success, ) = facet.delegatecall(msg.data);
    require(success, "Delegatecall failed");
  }
}

This code shows how the Diamond contract delegates calls to the correct facet using the function signature.

Execution Table

Step	Action	Input	Facet Selected	Delegatecall Result	Output
1	Receive call	functionA()	Lookup facets['functionA()']	facetA address found	Proceed
2	Delegatecall	Call facetA.functionA()	facetA	Execute facetA logic	Return result from facetA
3	Receive call	functionB()	Lookup facets['functionB()']	facetB address found	Proceed
4	Delegatecall	Call facetB.functionB()	facetB	Execute facetB logic	Return result from facetB
5	Receive call	functionX()	Lookup facets['functionX()']	No facet found	Revert call
6	Exit	No valid facet	None	Call reverted	Error returned

💡 Execution stops when no facet matches the function selector, causing a revert.

Variable Tracker

Variable	Start	After Step 1	After Step 3	After Step 5	Final
facets	{}	{'functionA()': facetA}	{'functionA()': facetA, 'functionB()': facetB}	{'functionA()': facetA, 'functionB()': facetB}	{'functionA()': facetA, 'functionB()': facetB}
msg.sig	N/A	functionA()	functionB()	functionX()	functionX()
facet	null	facetA	facetB	null	null

Key Moments - 3 Insights

Why does the Diamond contract use delegatecall instead of a normal call?

Because delegatecall runs the facet's code in the Diamond's storage context, preserving state and allowing modular upgrades. See execution_table steps 2 and 4 where delegatecall executes facet logic.

What happens if a function selector is not found in the facets mapping?

The call reverts because no facet handles that function. This is shown in execution_table step 5 and 6 where no facet is found and the call reverts.

How does the Diamond pattern help with contract upgrades?

It allows adding, replacing, or removing facets without redeploying the whole contract, by updating the facets mapping. This modularity is implied in variable_tracker where facets mapping changes over time.

Visual Quiz - 3 Questions

Look at the execution_table, what is the facet selected at Step 3 when functionB() is called?

A facetA

B null

C facetB

D No facet found

💡 Hint

Check the 'Facet Selected' column at Step 3 in the execution_table.

At which step does the call revert due to no facet found?

A Step 4

B Step 5

C Step 2

D Step 1

💡 Hint

Look for 'No facet found' in the 'Delegatecall Result' column in the execution_table.

If a new facet is added for functionX(), how would the variable 'facets' change after Step 5?

A It would include 'functionX()' mapped to the new facet

B It would remove 'functionB()'

C It would stay the same

D It would become empty

💡 Hint

Refer to variable_tracker showing how facets mapping updates when new functions are added.

Concept Snapshot

Diamond pattern (EIP-2535) allows a single contract to delegate calls to multiple smaller contracts called facets.
Uses a mapping from function selectors to facet addresses.
Calls are forwarded using delegatecall to preserve storage.
Enables modular upgrades by adding/replacing facets.
If no facet matches, the call reverts.
Common in blockchain for flexible contract design.

Full Transcript

The Diamond pattern (EIP-2535) is a way to build smart contracts that can be split into smaller parts called facets. The main contract, called the Diamond, receives calls and looks up which facet should handle the function based on the function signature. It then uses delegatecall to run the facet's code but keeps the Diamond's storage. This allows the contract to be upgraded by adding or changing facets without redeploying everything. If a function is called that no facet handles, the call will revert and return an error. The execution table shows how calls are routed step-by-step, and the variable tracker shows how the facets mapping changes as new facets are added. This pattern helps developers create flexible and upgradeable contracts on the blockchain.

Practice

1.

What is the main purpose of the Diamond pattern (EIP-2535) in blockchain smart contracts?

easy

A. To split a large contract into smaller, manageable facets

B. To increase the gas cost of contract deployment

C. To prevent any contract upgrades

D. To combine multiple unrelated contracts into one

Solution

1. Step 1: Understand the Diamond pattern concept

   The Diamond pattern divides a big contract into smaller parts called facets to organize code better.

2. Step 2: Identify the main benefit

   This splitting allows easier upgrades and management of smart contracts.

3. Final Answer:

   To split a large contract into smaller, manageable facets -> Option A

4. Quick Check:

   Diamond pattern = splitting contract into facets [OK]

Hint: Remember: Diamond pattern breaks big contracts into smaller parts [OK]

Common Mistakes:

• Thinking it prevents upgrades
• Assuming it increases deployment cost
• Confusing it with contract merging

2.

Which of the following is the correct Solidity syntax to declare a facet interface in the Diamond pattern?

interface IFacet {
    function myFunction() external;
}

easy

A. contract IFacet { function myFunction() public {} }

B. interface IFacet { function myFunction() external; }

C. library IFacet { function myFunction() internal; }

D. struct IFacet { function myFunction() external; }

Solution

1. Step 1: Identify correct Solidity declaration for interface

   Interfaces use the keyword interface and declare functions without bodies.

2. Step 2: Match function visibility and syntax

   Function in interface must be external and end with a semicolon, no body.

3. Final Answer:

   interface IFacet { function myFunction() external; } -> Option B

4. Quick Check:

   Interface syntax = interface IFacet { function myFunction() external; } [OK]

Hint: Interfaces have no function bodies and use 'external' functions [OK]

Common Mistakes:

• Using contract instead of interface
• Adding function bodies in interface
• Using wrong visibility like public or internal

3.

Given the following Solidity snippet using the Diamond pattern, what will be the output when calling diamond.facetFunction()?

contract FacetA {
    function facetFunction() external pure returns (string memory) {
        return "Facet A called";
    }
}

contract Diamond {
    FacetA facetA;
    constructor() {
        facetA = new FacetA();
    }
    function facetFunction() external view returns (string memory) {
        return facetA.facetFunction();
    }
}

medium

A. "Facet A called"

B. Compilation error due to missing function

C. "Diamond called"

D. Runtime error: function not found

Solution

1. Step 1: Understand contract interaction

   The Diamond contract creates an instance of FacetA and calls its facetFunction.

2. Step 2: Trace the function call and return value

   Calling diamond.facetFunction() returns the string from FacetA: "Facet A called".

3. Final Answer:

   "Facet A called" -> Option A

4. Quick Check:

   Diamond calls FacetA function = "Facet A called" [OK]

Hint: Diamond delegates calls to facets returning their outputs [OK]

Common Mistakes:

• Assuming Diamond returns its own string
• Expecting compilation error due to delegation
• Confusing runtime errors with correct delegation

4.

Identify the error in this simplified Diamond pattern Solidity code snippet:

contract Diamond {
    mapping(bytes4 => address) public facets;

    function addFacet(bytes4 selector, address facetAddress) public {
        facets[selector] = facetAddress;
    }

    fallback() external {
        address facet = facets[msg.sig];
        (bool success, ) = facet.delegatecall(msg.data);
        require(success, "Delegatecall failed");
    }
}

medium

A. Using delegatecall instead of call

B. Fallback function must be external payable

C. Mapping key type should be bytes32, not bytes4

D. Missing return statement in fallback function

Solution

1. Step 1: Analyze fallback function behavior

   The fallback uses delegatecall but does not return data to the caller.

2. Step 2: Identify missing return data forwarding

   Delegatecall returns data that must be returned by fallback to preserve call behavior.

3. Final Answer:

   Missing return statement in fallback function -> Option D

4. Quick Check:

   Fallback must return delegatecall data [OK]

Hint: Fallback must return delegatecall results to caller [OK]

Common Mistakes:

• Ignoring return data in fallback
• Confusing delegatecall with call
• Assuming payable is mandatory for fallback

5.

You want to upgrade a Diamond contract by adding a new facet with a function selector that already exists in another facet. What will happen if you do not remove the old selector before adding the new one?

hard

A. The Diamond will route calls to the new facet for that selector

B. The Diamond will have two facets for the same selector causing ambiguity

C. The old facet's function will still be called, ignoring the new one

D. The contract will fail to compile due to duplicate selectors

Solution

1. Step 1: Understand selector uniqueness in Diamond pattern

   Each function selector maps to exactly one facet address in the Diamond.

2. Step 2: Analyze what happens when adding duplicate selectors

   If you add a selector without removing the old one, the mapping still points to the old facet, so calls route there.

3. Final Answer:

   The old facet's function will still be called, ignoring the new one -> Option C

4. Quick Check:

   Duplicate selector without removal = old facet called [OK]

Hint: Remove old selector before adding new to update facet [OK]

Common Mistakes:

• Assuming Diamond supports multiple facets per selector
• Expecting compile-time errors for duplicates
• Thinking new facet automatically overrides old without removal