Diamond Helper Functions #158

0xCourtney · 2022-10-30T12:30:20Z

Summary

EIP2535 is a standard quickly growing in popularity and adoption. While Diamonds offer a great pathway for scaling contracts there are not many tools for managing deployments or upgrades. This PR introduces utility functions that provide developers with a consistent and reliable way of maintaining their contracts. The key goal here is to offer tools that perform the minimal changes necessary to add, replace, or remove facets from a Diamond.

Usage

General

diamondCut - calls Diamond.diamondCut
printDiamond - prints a table containing the registered and unregistered selectors

Deployment

addUnregisteredSelectors - adds unregistered selectors to the Diamond.

Upgrade

replaceRegisteredSelectors - replaces any selector which is registered to a different target address
removeRegisteredSelectors - removes the registered selector from the Diamond

Examples

// TestFacets.sol

contract Test1Facet {
    function test1Func1(bool) public returns (bytes32[] memory) {}
    function test1Func2(int128) external view returns (address) {}
    function test1Func3(address, address, address) external {}
}

contract Test1Facet1 {
    function test1Func1(bool) public returns (bytes32[] memory) {}
    function test1Func2() external view returns (address) {}
}

contract Test2Facet {
    function test2Func1() external pure returns (uint8) {}
    function test2Func2(bytes8) external view returns (bool) {}
}

// deploy.ts

// deploy Diamond
// registers selectors from Test1Facet and Test2Facet on Diamond
let facetCut = await addUnregisteredSelectors(Diamond, [Test1Facet, Test2Facet]);
await diamondCut(Diamond, facetCut);

// upgrade Diamond
// adds Test1Facet1.test1Func2, since the signature has changed
facetCut = await addUnregisteredSelectors(Diamond, [Test1Facet1]);
await diamondCut(Diamond, facetCut);

// replace Test1Facet.test1Func1 with Test1Facet1.test1Func1
facetCut = await replaceRegisteredSelectors(Diamond, [Test1Facet1]);
await diamondCut(Diamond, facetCut);

// removes Test1Facet.test1Func2 and Test1Facet.test1Func3
facetCut = await removeRegisteredSelectors(Diamond, [Test2Facet, Test1Facet1]);
await diamondCut(Diamond, facetCut);

Actions

Add tests to repo

NouDaimon

Awesome initiative! Eventually, these utility functions will prove very useful to third parties.

lib/diamonds.ts

0xCourtney · 2022-11-09T00:54:00Z

@NouDaimon thanks for the feedback! I have a bunch of changes on my local which I plan on pushing this week. I will update the description with my checklist of things before this is ready to come out of draft.

0xCourtney · 2022-11-09T12:53:28Z

Any recommendations on where I should add tests and contracts?

cc @ItsNickBarry

ItsNickBarry

Still a bit unsure about how to organize this, but definitely a good start.

@0xCourtney Can you list all the places where you think a developer would use the print function? As mentioned in an inline comment, in my opinion that function would fit best in a CLI package. How to print something is fundamentally more opinionated than SS is trying to be. But you might have some use cases in mind that would justify including it here.

I'll put some more thought in to a possible Hardhat plugin.

lib/diamonds.ts

ItsNickBarry · 2022-12-09T23:17:19Z

lib/diamonds.ts

+  }
+
+  return groupFacetCuts(facetCuts);
+}


The add/replace/remove function names imply that a transaction is sent, but really they just generate the FacetCut formatting. Should change the name to something like generateFacetCutsForAdd. Can you think of something better?

These functions are rather specific, so I think they should throw errors if certain passed data can't be added/removed/replaced.

I'd also like a function that takes a list of selectors and targets, and calculates the FacetCut diff needed to migrate an existing diamond to the given schema.

The add/replace/remove function names imply that a transaction is sent, but really they just generate the FacetCut formatting. Should change the name to something like generateFacetCutsForAdd. Can you think of something better?

I asked ChatGPT for help here, how about addUnregisteredSelectorsToFacetCut? Likewise, the other functions could be renamed replaceRegisteredSelectorsInFacetCut and removeRegisteredSelectorsFromFacetCut

I'd also like a function that takes a list of selectors and targets, and calculates the FacetCut diff needed to migrate an existing diamond to the given schema.

e702c36

These functions are rather specific, so I think they should throw errors if certain passed data can't be added/removed/replaced.

45b2dc4

This reverts commit 9c37405629b7321e0725de8bf30de1e51eb5f685.

0xCourtney · 2022-12-19T22:34:21Z

In 3d9d456 I introduced the concept of filters. A filter consists of an object containing a contract address and an array of selectors.

interface FacetFilter {
  contract: string;
  selectors: string[];
}

The only filter will add/replace/remove selectors defined in the only filter ignoring all other selectors for that contract. The exclude filter will ignore all selectors defined in the exclude filter for that contract, all other selectors will get added/replaced/removed.

await d.addUnregisteredSelectors(Diamond, [Test1Facet1])

// [{
//   target: '0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0',
//   action: 0,
//   selectors: [ '0xc2985578', '0x0716c2ae' ]
// }]

await d.addUnregisteredSelectors(
  Diamond,
  [Test1Facet1],
  [{ contract: Test1Facet1.address, selectors: ['0xc2985578'] }],
  [],
);

// [{
//   target: '0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0',
//   action: 0,
//   selectors: [ '0xc2985578' ]
// }]

await d.addUnregisteredSelectors(
  Diamond,
  [Test1Facet1],
  [],
  [{ contract: Test1Facet1.address,selectors: ['0xc2985578'] }],
)

// [{
//   target: '0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0',
//   action: 0,
//   selectors: [ '0x0716c2ae' ]
// }]

The only and exclude filters must not overlap, therefore a contract may define selectors in the only or exclude filter, not both.

…tate-solidity into diamond-helper

lib/diamonds.ts

lib/package.json

…xport Use `FacetCutAction` enum in tests

lib/diamond/utils.ts

ItsNickBarry · 2022-12-20T21:19:50Z

lib/diamond/filters.ts

+export interface FacetFilter {
+  contract: string;
+  selectors: string[];
+}


It looks like these FacetFilter objects are used in sets of 3 arrays, corresponding to the FacetCutAction types. Would it not be better to include the action in the FacetFilter type?

I can certainly look into this, I was already planning to replace the only and except parameters with filter in the add/replace/remove API, then add a type field to FacetFilter. The new FacetFilter could look something like this:

export interface FacetFilter { type: string; // "only" or "except" action: FacetCutAction; contract: string; selectors: string[]; }

lib/diamond/filters.ts

ItsNickBarry · 2022-12-20T21:29:12Z

lib/diamond/utils.ts

+  target: string = AddressZero,
+  data: string = '0x',
+) {
+  (await diamond.diamondCut(facetCut, target, data)).wait(1);


How exactly does wait work?

Resolves to the TransactionReceipt once the transaction has been included in the chain for confirms blocks. If confirms is 0, and the transaction has not been mined, null is returned.

It may be good to return the TransactionReceipt here. Otherwise, a user may not be able to detect errors or access the receipt, if needed.

ItsNickBarry · 2022-12-20T21:30:25Z

lib/diamond/utils.ts

+  return cuts;
+}
+
+export function printFacetCuts(


This doesn't seem to print anything.

Maybe getFacetCut is more appropriate, the function only structures the FacetCut object.

ItsNickBarry · 2022-12-20T21:32:28Z

lib/diamond/utils.ts

+  }
+
+  if (!selectorsReplaced) {
+    throw new Error('No selectors were replaced in FacetCut');


The errors are thrown if all changes are skipped, but I think we'll want to throw if any change is skipped. Need to think about this though.

Would this be the result of using filters or something else?

Co-authored-by: Nick Barry <itsnickbarry@protonmail.ch>

… FacetFilter

lib/diamond/utils.ts

jhubbardsf · 2023-03-07T14:23:19Z

Hey, anything happening with this PR? Does anyone need some help getting it finished? I saw a lot of promise in it.

ItsNickBarry · 2023-03-07T21:12:20Z

@jhubbardsf I've shifted focus to a WIP plugin that manages diamond upgrades. It's easier to add the functions I need there first, and then determine how to structure what's been added here. This will be merged eventually.

0xCourtney linked an issue Oct 30, 2022 that may be closed by this pull request

diamondCut utilities #65

Open

NouDaimon reviewed Nov 8, 2022

View reviewed changes

lib/diamonds.ts Outdated Show resolved Hide resolved

lib/diamonds.ts Outdated Show resolved Hide resolved

lib/diamonds.ts Outdated Show resolved Hide resolved

diamond utils draft

a7edda4

0xCourtney force-pushed the diamond-helper branch from 15ce376 to a7edda4 Compare November 10, 2022 20:16

0xCourtney requested a review from NouDaimon November 10, 2022 20:17

ItsNickBarry reviewed Dec 9, 2022

View reviewed changes

ItsNickBarry and others added 11 commits December 14, 2022 02:58

Merge branch 'master' into diamond-helper

420964c

remove printDiamond

047964e

removes composite type

9d3a62d

exports facet cut action

9d3b060

removes cli-table3 package

20bf78e

imports ethersproject packages

b2eda57

Revert "remove printDiamond"

398ff37

This reverts commit 9c37405629b7321e0725de8bf30de1e51eb5f685.

removes printDiamond from external interface

f9a6c2c

throws if add/replace/remove fails

45b2dc4

adds only filter, refactors exclude

3d9d456

adds previewFacetCut

e702c36

0xCourtney requested a review from ItsNickBarry December 19, 2022 22:34

0xCourtney and others added 4 commits December 19, 2022 18:49

removes printDiamond

5f34d05

adds comments

1aa7db8

capitalize FacetCutAction enum types

f00863e

moves diamond utils to diamond subdirectory

c8195bc

0xCourtney marked this pull request as ready for review December 20, 2022 16:47

ItsNickBarry added 2 commits December 20, 2022 18:52

Merge branch 'diamond-helper' of github.com:solidstate-network/solids…

f43c14a

…tate-solidity into diamond-helper

Merge branch 'master' into diamond-helper

c93c0a5

ItsNickBarry reviewed Dec 20, 2022

View reviewed changes

lib/diamonds.ts Outdated Show resolved Hide resolved

lib/package.json Outdated Show resolved Hide resolved

use FacetCutAction enum in spec and test files

e5d19a2

ItsNickBarry and others added 4 commits December 20, 2022 20:22

fix dependency versions

dfac641

Merge pull request #176 from solidstate-network/diamond-helper-enum-e…

669a620

…xport Use `FacetCutAction` enum in tests

reorder declarations

cef5a3f

uses except instead of exclude

ce286c6

ItsNickBarry reviewed Dec 20, 2022

View reviewed changes

0xCourtney and others added 9 commits December 22, 2022 11:07

Update lib/diamond/utils.ts

a2a3c19

Co-authored-by: Nick Barry <itsnickbarry@protonmail.ch>

Update lib/diamond/utils.ts

c7df310

Co-authored-by: Nick Barry <itsnickbarry@protonmail.ch>

Update lib/diamond/filters.ts

7d6598e

Co-authored-by: Nick Barry <itsnickbarry@protonmail.ch>

rename

9d92ea0

updates comments

a9b12a5

rename

f4c211b

typo

dbf11d5

diamonCut returns receipt

871f868

consolidates only and execpt to single array, adds type and action to…

54da442

… FacetFilter

ItsNickBarry reviewed Dec 24, 2022

View reviewed changes

lib/diamond/utils.ts Show resolved Hide resolved

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Diamond Helper Functions #158

Diamond Helper Functions #158

0xCourtney commented Oct 30, 2022 •

edited

NouDaimon left a comment

0xCourtney commented Nov 9, 2022

0xCourtney commented Nov 9, 2022

ItsNickBarry left a comment

ItsNickBarry Dec 9, 2022

ItsNickBarry Dec 9, 2022

ItsNickBarry Dec 9, 2022

0xCourtney Dec 14, 2022 •

edited

0xCourtney Dec 19, 2022

0xCourtney Dec 19, 2022

0xCourtney commented Dec 19, 2022

ItsNickBarry Dec 20, 2022

0xCourtney Dec 22, 2022

0xCourtney Dec 22, 2022

ItsNickBarry Dec 20, 2022

0xCourtney Dec 22, 2022

0xCourtney Dec 22, 2022

ItsNickBarry Dec 20, 2022

0xCourtney Dec 22, 2022 •

edited

0xCourtney Dec 22, 2022

ItsNickBarry Dec 20, 2022

0xCourtney Dec 22, 2022

jhubbardsf commented Mar 7, 2023 •

edited

ItsNickBarry commented Mar 7, 2023

Diamond Helper Functions #158

Are you sure you want to change the base?

Diamond Helper Functions #158

Conversation

0xCourtney commented Oct 30, 2022 • edited

Summary

Usage

General

Deployment

Upgrade

Examples

Actions

NouDaimon left a comment

Choose a reason for hiding this comment

0xCourtney commented Nov 9, 2022

0xCourtney commented Nov 9, 2022

ItsNickBarry left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xCourtney Dec 14, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xCourtney commented Dec 19, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xCourtney Dec 22, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhubbardsf commented Mar 7, 2023 • edited

ItsNickBarry commented Mar 7, 2023

0xCourtney commented Oct 30, 2022 •

edited

0xCourtney Dec 14, 2022 •

edited

0xCourtney Dec 22, 2022 •

edited

jhubbardsf commented Mar 7, 2023 •

edited