status-im/EIPs
2
0
Fork 0
mirror of https://github.com/status-im/EIPs.git synced 2025-02-23 20:28:21 +00:00
Code Issues Projects Releases Wiki Activity

Create EIP-2767: Contract Ownership Governance (#2767)

Browse Source 
A standard interface for Governance contracts that administratively decentralize the ownership of smart contracts.
This commit is contained in:
soham 2020-07-18 08:14:46 +05:30 committed by GitHub
parent 156e2df46e
commit 490425927d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 239 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
EIPS/eip-2767.md Normal file
View File

@ -0,0 +1,239 @@
---
eip: 2767
title: Contract Ownership Governance
author: Soham Zemse (@zemse), Nick Mudge (@mudgen)
discussions-to: https://github.com/ethereum/EIPs/issues/2766
status: Draft
type: Standards Track
category: ERC
created: 2020-07-04
requires: 173, 165, 191
---
## Simple Summary
<!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP.-->
A standard interface for Governance contracts that administratively decentralize the ownership of smart contracts.
## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->
The following standard allows for the implementation of a standard API for a Governance smart contract. This standard provides basic functionality for on-chain and off-chain governance inheriting equal or privileged voting rights. Existing `ERC-173` compatible contracts can upgrade from private key wallet ownership to a Governance smart contract. Smart contracts that use a Governance contract are more administratively decentralised and adhering to a standard API enables tools to populate governance information to dApp users.
## Motivation
<!--The motivation is critical for EIPs that want to change the Ethereum protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the EIP solves. EIP submissions without sufficient motivation may be rejected outright.-->
Traditionally, many contracts that require that they be owned or controlled in some way use `ERC-173` which standardized the use of ownership in the smart contracts. For example to withdraw funds or perform administrative actions.
```solidity
contract dApp {
function doSomethingAdministrative() external onlyOwner {
// admin logic that can be performed by a single wallet
}
}
```
Often, such administrative rights for a contract are written for maintenance purpose but users need to trust the owner. Rescue operations by an owner have raised questions on decentralised nature of the projects. Also, there is a possibility of compromise of an owner's private key.
At present, there are various implementation ideas for handling governance. Adhering to a standard API would enable general tools (like EtherScan) to populate governance information, thus increasing transparency to users. This can result in a wide adoption for contract governance.
## Specification
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->
#### Notes
- The following specifications use syntax from Solidity 0.6.0 (or above)
- Governor is the board member who has voting right.
- Power represents the voting privilege of a governor.
A contract that is compliant with `ERC-2767` shall implement the following interface:
```solidity
/// @title ERC-2767 Governance with Privileged Voting Rights
/// @dev ERC-165 InterfaceID: 0x4fe54581
interface ERC2767 {
/// @dev This emits when governor power changes
event GovernorPowerUpdated(address indexed governor, uint256 power);
/// @notice Gets the consensus power of the governor
/// @param _governor Address of the governor
/// @return The governor's voting power
function powerOf(address _governor) external view returns (uint256);
/// @notice Gets the sum of the power of all governors
/// @return Sum of the power of all governors
function totalPower() external view returns (uint256);
/// @notice Gets number votes required for achieving consensus
/// @return Required number of consensus votes
function required() external view returns (uint256);
/// @notice Updates governor statuses
/// @param _governor Governor address
/// @param _newPower New power for the governor
/// @dev Only Governance can call
function setGovernor(address _governor, uint256 _newPower) external;
}
```
Implementations that require equal governance rights between the governors can simply have equal power values for every governor.
There is a possibility that `totalPower()` changes rapidly due to adding or removing governors. This can result in having a fixed `required()` return value easier or difficult to achieve. Implementations can have custom logic that affect the return value of `required()`. For example the return value of `required()` can be changed by custom logic in order to maintain `51%` of `totalPower()`. So if more governors are added in such implementations, the `required()` return value would automatically take that into account.
### Interface Identification
An `ERC-2767` Governance Contract should also implement `ERC-165`. This helps general tools to identify whether a contract is a `ERC-2767` Governance contract.
```solidity
interface ERC165 {
/// @notice Query if a contract implements an interface
/// @param interfaceID The interface identifier, as specified in ERC-165
/// @dev Interface identification is specified in ERC-165. This function
/// uses less than 30,000 gas.
/// @return `true` if the contract implements `interfaceID` and
/// `interfaceID` is not 0xffffffff, `false` otherwise
function supportsInterface(bytes4 interfaceID) external view returns (bool);
}
```
### Transaction execution (Optional)
There are two optional interfaces for transaction execution: On-chain and Off-chain. A `ERC-2767` compatible governance contract can optionally implement one of them or both. The contract should specify the interfaceID(s) using `ERC-165`'s `supportsInterface` method.
#### On-chain
```solidity
/// @title ERC-2767 On-chain Governance
/// @dev ERC-165 InterfaceID: 0x947133b4
interface IGovernanceOnchain {
struct Transaction {
address destination;
uint256 value;
bytes data;
bool executed;
uint256 votes;
}
/// @dev Emits when a transaction is proposed
event TransactionCreated(uint256 indexed transactionId);
/// @dev Emits every time a governor confirms a transaction
event TransactionConfirmed(uint256 indexed transactionId);
/// @dev Emits whenever a governor takes back their confirmation
event TransactionRevoked(uint256 indexed transactionId);
/// @dev Emits when a transactions with enough confirmations is executed
event TransactionExecuted(uint256 indexed transactionId);
/// @notice Gets transaction parameters
/// @param _transactionId TransactionID
/// @return ABIV2 encoded Transaction struct
function getTransaction(uint256 _transactionId) external view returns (Transaction memory);
/// @notice Allows an governor to submit and confirm a transaction.
/// @param _destination Transaction target address, the governed contract
/// @param _value Transaction ether value
/// @param _data Transaction data payload
/// @return Returns transaction ID
function createTransaction(
address _destination,
uint256 _value,
bytes memory _data
) external returns (uint256);
/// @notice Allows a governor to confirm a transaction.
/// @param _transactionId Transaction ID
function confirmTransaction(uint256 _transactionId) external;
/// @notice Allows a governor to revoke a confirmation for a transaction
/// @param _transactionId Transaction ID
function revokeConfirmation(uint256 _transactionId) external;
/// @notice Calls the governed contract to perform administrative task
/// @param _transactionId Transaction ID
/// @dev Only Governance can call
function executeTransaction(uint256 _transactionId) external;
}
```
A governor proposes a transaction by calling `createTransaction` passing the parameters. Following this, rest of the governors can choose to confirm the transaction by calling `confirmTransaction`. If at later point of time, a governor wishes to take back their vote, they can call `revokeConfirmation`. Once a transaction reaches enough confirmations, it can be executed by calling `confirmTransaction`. The `confirmTransaction` method can internally call `executeTransaction` after it's primary logic if required votes have been registered.
#### Off-chain
```solidity
/// @title ERC-2767 Off-chain Governance
/// @dev ERC-165 InterfaceID: 0x32542713
interface IGovernanceOffchain {
/// @notice Get the transactions count
/// @dev To be used as nonce
/// @return The transactions count
function transactionsCount() external view returns (uint256);
/// @notice Calls the governed contract to perform an administrative task
/// @param _nonce Serial number of transaction
/// @param _destination Address of contract to make a call to, should be governed contract address
/// @param _data Input data in the transaction
/// @param _signatures Signatures of governors collected off chain
/// @dev The signatures are required to be sorted to prevent duplicates
/// @dev Only Governance can call
function executeTransaction(
uint256 _nonce,
address _destination,
bytes memory _data,
bytes[] memory _signatures
) external payable;
}
```
Anyone can take an initiative to execute a transaction by preparing a `ERC-191` signed data `0x 19 00 <20 bytes address> <32 bytes nonce> <20 bytes to-address> <input data>` and collect signatures from required governors. The contract logic should expect signatures to be sorted, this is to save the expenditure gas to prevent duplicate signatures. If signatures are sorted, valid, and the required number of them (or more), the governance contract will make a call to the governed contract to perform the administrative task.
## Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
The goals of this EIP have been the following:
- standardize API of Governance contracts for governed contracts.
- enable existing `ERC-173` ownership smart contracts to become administratively decentralised.
## Backwards Compatibility
<!--All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
Smart contracts that are `ERC-173` compliant can transfer their ownership to a Governance contract. This enables existing contracts to become compatible with `ERC-2767`.
However, there are some existing projects with governance implementations and most of them have custom APIs, since a standard did not exist. Such projects need to deploy a new governance contract and transfer ownership to it to be `ERC-2767` compatible. Not having an `ERC-2767` compatible governance contract means only that general tools might be able to populate their governance information.
<!-- ## Test Cases -->
<!--Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.-->
## Implementation
<!--The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
The reference implementations are available in this [repository](https://github.com/zemse/contract-ownership-governance).
1. Governance Onchain with Equal Voting Rights ([Contract](https://github.com/zemse/contract-ownership-governance/blob/master/contracts/GovernanceOnchainEqual.sol), [Tests](https://github.com/zemse/contract-ownership-governance/blob/master/test/suites/OnchainEqual.test.ts))
2. Governance Offchain with Privileged Voting Rights ([Contract](https://github.com/zemse/contract-ownership-governance/blob/master/contracts/GovernanceOffchainPrivileged.sol), [Tests](https://github.com/zemse/contract-ownership-governance/blob/master/test/suites/OffchainPrivileged.test.ts))
## Security Considerations
<!--All EIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. EIP submissions missing the "Security Considerations" section will be rejected. An EIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.-->
The signatures in off-chain governance implementation should follow recommendations of `ERC-191`.
```
0x 19 00 <20 bytes governance address> <32 bytes nonce> <20 bytes to-address> <input data>.
```
To prevent repeated signatures in the `signatures` array, it is required that caller of `executeTransaction` should sort the signatures based on increasing addresses.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).