From 97388d60dd157bd9e586c07aa44f520b110cafd6 Mon Sep 17 00:00:00 2001 From: Illia Polosukhin Date: Fri, 9 Oct 2020 07:17:20 -0700 Subject: [PATCH 1/2] Smart Contract Upgradability --- specs/SUMMARY.md | 1 + specs/Standards/README.md | 1 + specs/Standards/Upgradability.md | 56 ++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 specs/Standards/Upgradability.md diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index a0fa8156b..655665f3d 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -48,3 +48,4 @@ - [Economics](Economics/README.md) - [Standards](Standards/README.md) - [Fungible Token](Standards/Tokens/FungibleToken.md) + - [Smart Contract Upgradability](Standards/Upgradability.md) diff --git a/specs/Standards/README.md b/specs/Standards/README.md index 2e500c052..e18966c68 100644 --- a/specs/Standards/README.md +++ b/specs/Standards/README.md @@ -1,3 +1,4 @@ ## Standards - [Fungible Token Standard](Tokens/FungibleToken.md) +- [Smart Contract Upgradability](Upgradability.md) diff --git a/specs/Standards/Upgradability.md b/specs/Standards/Upgradability.md new file mode 100644 index 000000000..b3bcfccef --- /dev/null +++ b/specs/Standards/Upgradability.md @@ -0,0 +1,56 @@ +# Smart contract upgradability + +In NEAR smart contracts are upgradable by default. + +## Non-upgradable + +There are many contracts that won't be upgradable. +There are two ways to facilitate upgrades: access keys and contract re-deploying it's own code. + +To determine if contract is not upgradable, need to check that contract doesn't have any full access keys and that contract's code doesn't contain any `DeployContract` calls to itself. + +Additionally, contract code can contain ability to add FullAccessKeys to itself, and in this way return back control to the faciliatator (for example multisig and lockup contracts have this ability under certain circumstances). + +## Accessible contract + +Accessible contracts are contracts that have access keys with ability to re-deploy new code on them. +Usually this will be used for development or in some highly permissioned setting. + +For example contracts like multisig is really owned by the person or people who control it and hence they can re-deploy the code on it to upgrade or remove multisig. + +## Owner-pattern + +Owner pattern means that contract's upgradability is owned by a different account. +This allows to introduce a more sophisticated management, anything from multisig to DAO. +And also allows to evolve the management over time. + +Owner upgradable pattern introduces next set of methods: + +``` + /// Returns current owner account. + get_owner() -> AccountId + + /// Sets new owner. If owner is set to `system` this contract is considered to be non-upgradable without hard forks. + set_owner(owner: AccountId) + + /// Returns how long between staging code and deploy can be called in nanoseconds. + /// Usually staging duration is set at deploy. Good defaults are 1 and 7 days. + get_staging_duration() -> WrappedDuration + + /// Stages new contract on the given account. + /// Can only be called by owner. + /// This means that contract code is ready to be activated after specific staging time passes. + /// Caller is responsible for attaching extra balance to cover storage. + stage_code(code: bytes) + + /// Deploys staged code. + /// Can only be called by owner. + /// If there is no staged code, will fail. + deploy_code() +``` + +TBD: do we want to have a way to change staging duration? + +## State migrations + +This section is TBD on state migration patters From be7c96473a3fcc9bf4d0f06355bd648d25d36874 Mon Sep 17 00:00:00 2001 From: Illia Polosukhin Date: Fri, 9 Oct 2020 07:36:33 -0700 Subject: [PATCH 2/2] Fix up some language --- specs/Standards/Upgradability.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specs/Standards/Upgradability.md b/specs/Standards/Upgradability.md index b3bcfccef..7f9def9f7 100644 --- a/specs/Standards/Upgradability.md +++ b/specs/Standards/Upgradability.md @@ -1,36 +1,40 @@ # Smart contract upgradability -In NEAR smart contracts are upgradable by default. +In NEAR smart contracts are upgradable in-place by default. +This means that given a specific `account-id` - the contract code may change depending on various rules. ## Non-upgradable -There are many contracts that won't be upgradable. -There are two ways to facilitate upgrades: access keys and contract re-deploying it's own code. +There are many contracts that should not be upgradable. + +There are two ways that contract code can be upgraded in-place: using an access key and contract re-deploying it's own code. To determine if contract is not upgradable, need to check that contract doesn't have any full access keys and that contract's code doesn't contain any `DeployContract` calls to itself. -Additionally, contract code can contain ability to add FullAccessKeys to itself, and in this way return back control to the faciliatator (for example multisig and lockup contracts have this ability under certain circumstances). +Additionally, contract code can contain ability to add FullAccessKeys to itself, and in this way return back control to the facilitator (for example multisig and lockup contracts have this ability under certain circumstances). ## Accessible contract Accessible contracts are contracts that have access keys with ability to re-deploy new code on them. -Usually this will be used for development or in some highly permissioned setting. -For example contracts like multisig is really owned by the person or people who control it and hence they can re-deploy the code on it to upgrade or remove multisig. +Usually this will be used for development or in some highly permissioned settings. + +For example, contracts like multisig is really owned by the person or people who control it and hence they can re-deploy the code on it to upgrade or remove multisig. ## Owner-pattern Owner pattern means that contract's upgradability is owned by a different account. -This allows to introduce a more sophisticated management, anything from multisig to DAO. -And also allows to evolve the management over time. -Owner upgradable pattern introduces next set of methods: +This allows to introduce a more sophisticated management, anything from multisig to DAO. This also allows to easily evolve the management over time. For example, starting from simple account, one can change owner later to multisig and later upgrade to a DAO. + +Owner upgradable pattern introduces next set of methods on a contract that follows this standard: ``` /// Returns current owner account. get_owner() -> AccountId /// Sets new owner. If owner is set to `system` this contract is considered to be non-upgradable without hard forks. + /// Can only be called by owner. set_owner(owner: AccountId) /// Returns how long between staging code and deploy can be called in nanoseconds.