Adds a new section to the documentation on "proxy patterns" #288
Conversation
eternauta1337
force-pushed
the
docs-proxy-patterns
branch
from
fc46679
to
3fc5ba1
Compare
…orage proxy pattern.
There was a problem hiding this comment.
I think that these articles from advanced topics should be merged into this page:
https://docs.zeppelinos.org/docs/advanced.html#the-proxy-system
https://docs.zeppelinos.org/docs/advanced.html#preserving-the-storage-structure
https://docs.zeppelinos.org/docs/advanced.html#initializers-vs-constructors
| @@ -0,0 +1,68 @@ | |||
| --- | |||
| id: proxies | |||
| title: Proxy Pattern | |||
There was a problem hiding this comment.
I would like to brand this:
The ZeppelinOS Upgrade Pattern
The problem here is that the ideas for this come from many different places, so maybe at the end we can add some generic thanks to everybody researching about upgradeability in ethereum.
@martriay what do you think?
There was a problem hiding this comment.
Keep in mind that the title has to fit in the sidebar =D
packages/docs/docs/docs/proxies.md
Outdated
|
|
||
| This code can be put in the fallback function of a proxy, and will forward any call to any function with any set of parameters to the logic contract without it needing to know anything in particular of the logic contract's interface. In essence, (1) the `calldata` is copied to memory, (2) the call is forwarded to the logic contract, (3) the return data from the call to the logic contract is retrieved, and (4) the returned data is forwarded back to the caller. | ||
|
|
||
| A very important thing to note is that the code makes use of `delegatecall` which executes the callee's code in the context of the caller's state. That is, the logic contract controls the proxy's state and the logic contract's state is meaningless. Thus, the proxy doesn't forward transactions to and from the logic contract, but also represents the pair's state. The state is in the proxy and the logic is in the particular implementation that the proxy points to. To put it in yet another way, the "what" is in the proxy contract and the "how" is in the logic contract. |
There was a problem hiding this comment.
Link to delegatecall's docs.
doesn't forward -> doesn't only forward
There was a problem hiding this comment.
I'm not sure I like the last sentence about "what" and "how". What would you think of mentioning instead that the state variables are in the proxy, and the functions are in the logic?
There was a problem hiding this comment.
I don't like that because it may confuse the user. One may think that variables need to be declared in the proxy in and functions in the implementation.
Removing my sentence and replacing it with nothing for now.
|
@ElOpio In this last commit I removed a few sections from advanced.md and merged them into proxies.md. My criteria was "incorporate what the items in advanced.md describe that is not described in the items in proxies.md and then delete them." |
packages/docs/docs/docs/proxies.md
Outdated
| |... | | | ||
| |... | | | ||
|
|
||
| An example of how the randomized storage is achieved: |
There was a problem hiding this comment.
I wouldn't use the word random, it sounds not-robust, I'd rather use something like fixed, explaining that we choose a specific position making sure that Solidity won't ever use it
(WIP)
Fixes #151