Add page on smart contract upgradeability #6472

emmanuel-awosika · 2022-05-26T11:54:00Z

This page provides a high-level introduction to smart contract upgrades for developers.

Description

This is a review of various patterns for upgrading Ethereum smart contracts. It also contains information on the pros and cons of smart contract upgrades and recommendations for using upgrades safely.

Related Issue

Closes #1511

This page provides a high-level introduction to smart contract upgrades for developers.

samajammin · 2022-05-26T17:36:38Z

Awesome, thanks! Looking forward to reviewing this 😄

Curious, are you familiar with the diamond pattern at all?

I feel like that could be another good approach to list. I don't think adding that would block this PR in any way, just wanted to call that out.

emmanuel-awosika · 2022-05-29T09:18:05Z

Awesome, thanks! Looking forward to reviewing this 😄

Curious, are you familiar with the diamond pattern at all?

https://github.com/mudgen/awesome-diamonds

https://eip2535diamonds.substack.com/p/introduction-to-the-diamond-standard?s=w

I feel like that could be another good approach to list. I don't think adding that would block this PR in any way, just wanted to call that out.

Yeah, I came across the concept while researching, but I thought I'd just focus on upgrade patterns with considerable usage (I didn't see many examples of projects using the diamond pattern). I did go through Nick Mudgen's Substack blog, and it looks like some audited projects have implemented it.

My GitHub is having an issue at the moment (I can't edit files or propose changes), so I can't add it. But I'll go through those resources and prepare to add a section for diamond upgrades once I can.

emmanuel-awosika · 2022-05-31T09:10:21Z

Awesome, thanks! Looking forward to reviewing this 😄

Curious, are you familiar with the diamond pattern at all?

https://github.com/mudgen/awesome-diamonds

https://eip2535diamonds.substack.com/p/introduction-to-the-diamond-standard?s=w

I feel like that could be another good approach to list. I don't think adding that would block this PR in any way, just wanted to call that out.

Hi @samajammin, I just updated the page to add the diamond pattern (also contrasted with proxy patterns since they are similar). The update also includes a reference to the smart contract size limit and how the diamond pattern solves that, so maybe it closes this issue?

emmanuel-awosika · 2022-06-02T09:53:36Z

Hi @samajammin. So, most of the articles I read on upgrading contracts had some code examples to demonstrate the concepts. I don't code, so I couldn't create example code snippets. But the OpenZeppelin article has some useful code snippets, and I wanted to suggest if we could use them?

Perhaps someone on the team can look at the code and see if they can create a version for the article. Here are two examples for proxy patterns and diamond patterns:

Proxy patterns

// Sample code, do not use in production!
contract Proxy {
address implementation;
fallback() external payable {
return implementation.delegatecall.value(msg.value)(msg.data);
}
}

Diamond pattern

// Sample code, do not use in production!
contract Proxy {
mapping(bytes4 => address) implementations;
fallback() external payable {
address implementation = implementations[msg.sig];
return implementation.delegatecall.value(msg.value)(msg.data);
}
}

This article has some code examples for the strategy/interface pattern and the data separation patterns, too. They were too long to copy here, but maybe they can help with creating examples for the page.

samajammin · 2022-07-11T17:16:09Z

Hey @emmanuel-awosika! Apologies for going radio silent here... 😳

I've reached out to a few folks who could potentially give this a technical review. Hopefully they can take a look. If not, we'll try to get this merged by the end of this week.

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

Amxx · 2022-07-12T08:00:40Z

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

+
+The diamond pattern can be considered an improvement on the proxy pattern. Diamond patterns differ from proxy patterns because the proxy contract delegates function calls to more than one logic contract. 
+
+The logic contracts in the diamond pattern are known as *facets*. To make the diamond pattern work, you need to create an array in the proxy contract that maps [function selectors](https://docs.soliditylang.org/en/v0.8.12/abi-spec.html#function-selector) to different facet addresses. 


that is usually a mapping, not an array. might be confusing to some.

Thanks. Fixed this in the page now.

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

Amxx · 2022-07-12T08:05:39Z

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

+4. Be aware of the costs involved in upgrading contracts. For instance, copying state (e.g., user balances) from an old contract to a new contract during contract migration may require more than one transaction, meaning more gas fees. 
+
+## Resources {#resources}
+**OpenZeppelin Upgrades OS - _A suite of tools for deploying and securing upgradeable smart contracts._**


It's called OpenZeppelin Upgrades plugins now.

Fixed this now.

Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>

Edits to incorporate feedback.

wackerow

This looks great @emmanuel-awosika! Sorry for the delays on this.. Topic is certainly not one I'm an expert in, so as always it would nice for others to weigh in, but I don't think it needs to be blocked before then.

Just left a couple small adjustments/comments, but after that I think we can pull this in. Nice job!

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

wackerow · 2022-07-13T00:54:19Z

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

+| A smart contract upgrade can make it easier to fix vulnerabilities discovered in the post-deployment phase.            | Upgrading smart contracts negates the idea of code immutability, which has implications for decentralization and security.                                          |
+| Developers can use upgrades to add new features to smart contract | Users must trust developers not to modify smart contracts arbitrarily.  |
+| Smart contract upgrades can improve safety for end-users since bugs can be fixed quickly.                              | Programming upgrade functionality into smart contracts adds another layer of complexity and increases the possibility of critical flaws.                        |
+| The opportunity to upgrade smart contracts may encourage developers to launch projects faster without doing due dilligence during the development phase. | Insecure access control or centralization in smart contracts can make it easier for malicious actors to perform unauthorized upgrades.


The opportunity to upgrade smart contracts may encourage developers to launch projects faster without doing due dilligence during the development phase.

Is this supposed to be in the "pro" column worded this way?

(Also, "diligence")

That's definitely a mistake. I'll move it to the cons section.

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md

Co-authored-by: Paul Wackerow <54227730+wackerow@users.noreply.github.com>

Edits to incorporate feedback.

wackerow

Great work @emmanuel-awosika! Thank you for another awesome PR 🙏 Pulling it in now

emmanuel-awosika · 2022-07-14T04:21:58Z

Great work @emmanuel-awosika! Thank you for another awesome PR 🙏 Pulling it in now

Thanks for reviewing, @wackerow. :)

Add page on smart contract upgradeability

f801b6f

This page provides a high-level introduction to smart contract upgrades for developers.

emmanuel-awosika requested review from samajammin, wackerow, corwintines, pettinarip and minimalsm as code owners May 26, 2022 11:54

github-actions bot added content 🖋️ This involves copy additions or edits review needed 👀 labels May 26, 2022

Update index.md

3acc252

Amxx reviewed Jul 12, 2022

View reviewed changes

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md Outdated Show resolved Hide resolved

Amxx reviewed Jul 12, 2022

View reviewed changes

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md Outdated Show resolved Hide resolved

Amxx reviewed Jul 12, 2022

View reviewed changes

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md Outdated Show resolved Hide resolved

Amxx reviewed Jul 12, 2022

View reviewed changes

src/content/developers/docs/smart-contracts/upgrading-smart-contracts/index.md Show resolved Hide resolved

Amxx reviewed Jul 12, 2022

View reviewed changes

emmanuel-awosika and others added 2 commits July 12, 2022 14:48

Apply suggestions from code review

f712ab3

Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>

Update index.md

73f34f7

Edits to incorporate feedback.

wackerow requested changes Jul 13, 2022

View reviewed changes

emmanuel-awosika and others added 2 commits July 13, 2022 17:31

Apply suggestions from code review

98b5bf2

Co-authored-by: Paul Wackerow <54227730+wackerow@users.noreply.github.com>

Update index.md

9fdeb27

Edits to incorporate feedback.

wackerow approved these changes Jul 14, 2022

View reviewed changes

wackerow merged commit 537244c into ethereum:dev Jul 14, 2022

wackerow mentioned this pull request Jul 14, 2022

Deploy v4.7.0 #7061

Merged

samajammin mentioned this pull request Jul 16, 2022

Upgrading contracts nav #7095

Merged

samajammin mentioned this pull request Jul 16, 2022

Q2 2022 ethereum.org product roadmap #6161

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add page on smart contract upgradeability #6472

Add page on smart contract upgradeability #6472

emmanuel-awosika commented May 26, 2022 •

edited by minimalsm

Loading

samajammin commented May 26, 2022

emmanuel-awosika commented May 29, 2022

emmanuel-awosika commented May 31, 2022

emmanuel-awosika commented Jun 2, 2022

samajammin commented Jul 11, 2022

Amxx Jul 12, 2022

emmanuel-awosika Jul 12, 2022

Amxx Jul 12, 2022

emmanuel-awosika Jul 12, 2022

wackerow left a comment

wackerow Jul 13, 2022

emmanuel-awosika Jul 13, 2022

wackerow left a comment

emmanuel-awosika commented Jul 14, 2022


		The diamond pattern can be considered an improvement on the proxy pattern. Diamond patterns differ from proxy patterns because the proxy contract delegates function calls to more than one logic contract.

		The logic contracts in the diamond pattern are known as facets. To make the diamond pattern work, you need to create an array in the proxy contract that maps [function selectors](https://docs.soliditylang.org/en/v0.8.12/abi-spec.html#function-selector) to different facet addresses.

Add page on smart contract upgradeability #6472

Add page on smart contract upgradeability #6472

Conversation

emmanuel-awosika commented May 26, 2022 • edited by minimalsm Loading

Description

Related Issue

samajammin commented May 26, 2022

emmanuel-awosika commented May 29, 2022

emmanuel-awosika commented May 31, 2022

emmanuel-awosika commented Jun 2, 2022

samajammin commented Jul 11, 2022

Amxx Jul 12, 2022

Choose a reason for hiding this comment

emmanuel-awosika Jul 12, 2022

Choose a reason for hiding this comment

Amxx Jul 12, 2022

Choose a reason for hiding this comment

emmanuel-awosika Jul 12, 2022

Choose a reason for hiding this comment

wackerow left a comment

Choose a reason for hiding this comment

wackerow Jul 13, 2022

Choose a reason for hiding this comment

emmanuel-awosika Jul 13, 2022

Choose a reason for hiding this comment

wackerow left a comment

Choose a reason for hiding this comment

emmanuel-awosika commented Jul 14, 2022

emmanuel-awosika commented May 26, 2022 •

edited by minimalsm

Loading