Abstract
The EIP standardizes the management of smart contracts within the decentralized application ecosystem. It enables protocols to become upgradeable and reduces their maintenance threshold. This EIP additionally introduces a smart contract dependency injection mechanism to audit dependency usage, to aid larger composite projects.
Motivation
In the ever-growing Ethereum, projects tend to become more and more complex. Modern protocols require portability and agility to satisfy customer needs by continuously delivering new features and staying on pace with the industry. However, the requirement is hard to achieve due to the immutable nature of blockchains and smart contracts. Moreover, the increased complexity and continuous delivery bring bugs and entangle the dependencies between the contracts, making systems less supportable.
Applications that have a clear facade and transparency upon their dependencies are easier to develop and maintain. The given EIP tries to solve the aforementioned problems by presenting two concepts: the contracts registry and the dependant.
The advantages of using the provided pattern might be:
- Structured smart contracts management via specialized contract.
- Ad-hoc upgradeability provision.
- Runtime smart contracts addition, removal, and substitution.
- Dependency injection mechanism to keep smart contracts’ dependencies under control.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.
ContractsRegistry
The ContractsRegistry MUST implement the following interface:
pragma solidity ^0.8.0;
interface IContractsRegistry {
/**
* @notice REQUIRED The event that is emitted when the non-proxy contract gets added to the registry
* @param name the name of the contract
* @param contractAddress the address of the added contract
*/
event ContractAdded(string name, address contractAddress);
/**
* @notice REQUIRED The event that is emitted when the proxy contract gets added to the registry
* @param name the name of the contract
* @param contractAddress the address of the added proxy contract
* @param implementation the address of the proxy implementation
*/
event ProxyContractAdded(string name, address contractAddress, address implementation);
/**
* @notice REQUIRED The event that is emitted when the proxy contract gets upgraded through the registry
* @param name the name of the contract
* @param newImplementation the address of the new proxy implementation
*/
event ProxyContractUpgraded(string name, address newImplementation);
/**
* @notice REQUIRED The event that is emitted when the contract gets removed from the registry
* @param name the name of the removed contract
*/
event ContractRemoved(string name);
/**
* @notice REQUIRED The function that returns an associated contract by the name
* @param name the name of the contract
* @return the address of the contract
*/
function getContract(string calldata name) external view returns (address);
/**
* @notice OPTIONAL The function that checks if a contract with a given name has been added
* @param name the name of the contract
* @return true if the contract is present in the registry
*/
function hasContract(string calldata name) external view returns (bool);
/**
* @notice RECOMMENDED The function that returns the admin of the added proxy contracts
* @return the proxy admin address
*/
function getProxyUpgrader() external view returns (address);
/**
* @notice RECOMMENDED The function that returns an implementation of the given proxy contract
* @param name the name of the contract
* @return the implementation address
*/
function getImplementation(string calldata name) external view returns (address);
/**
* @notice REQUIRED The function that injects dependencies into the given contract.
* MUST call the setDependencies() with address(this) and bytes("") as arguments on the substituted contract
* @param name the name of the contract
*/
function injectDependencies(string calldata name) external;
/**
* @notice REQUIRED The function that injects dependencies into the given contract with extra data.
* MUST call the setDependencies() with address(this) and given data as arguments on the substituted contract
* @param name the name of the contract
* @param data the extra context data
*/
function injectDependenciesWithData(
string calldata name,
bytes calldata data
) external;
/**
* @notice REQUIRED The function that upgrades added proxy contract with a new implementation.
* MUST emit ProxyContractUpgraded event
* @param name the name of the proxy contract
* @param newImplementation the new implementation the proxy will be upgraded to
*
* It is the Owner's responsibility to ensure the compatibility between implementations
*/
function upgradeContract(string calldata name, address newImplementation) external;
/**
* @notice RECOMMENDED The function that upgrades added proxy contract with a new implementation, providing data
* MUST emit ProxyContractUpgraded event
* @param name the name of the proxy contract
* @param newImplementation the new implementation the proxy will be upgraded to
* @param data the data that the new implementation will be called with. This can be an ABI encoded function call
*
* It is the Owner's responsibility to ensure the compatibility between implementations
*/
function upgradeContractAndCall(
string calldata name,
address newImplementation,
bytes calldata data
) external;
/**
* @notice REQUIRED The function that adds pure (non-proxy) contracts to the ContractsRegistry. The contracts MAY either be
* the ones the system does not have direct upgradeability control over or the ones that are not upgradeable by design
* MUST emit ContractAdded event
* @param name the name to associate the contract with
* @param contractAddress the address of the contract
*/
function addContract(string calldata name, address contractAddress) external;
/**
* @notice REQUIRED The function that adds the contracts and deploys the Transaprent proxy above them.
* It MAY be used to add contract that the ContractsRegistry has to be able to upgrade
* MUST emit ProxyContractAdded event
* @param name the name to associate the contract with
* @param contractAddress the address of the implementation
*/
function addProxyContract(string calldata name, address contractAddress) external;
/**
* @notice RECOMMENDED The function that adds an already deployed proxy to the ContractsRegistry. It MAY be used
* when the system migrates to the new ContractRegistry. In that case, the new ProxyUpgrader MUST have the
* credentials to upgrade the newly added proxies
* MUST emit ProxyContractAdded event
* @param name the name to associate the contract with
* @param contractAddress the address of the proxy
*/
function justAddProxyContract(string calldata name, address contractAddress) external;
/**
* @notice REQUIRED The function to remove contracts from the ContractsRegistry
* MUST emit ContractRemoved event
* @param name the associated name with the contract
*/
function removeContract(string calldata name) external;
}
- The
ContractsRegistryMUST deploy theProxyUpgradercontract in the constructor that MUST be set as an admin ofTransparentproxies deployed viaaddProxyContractmethod. - It MUST NOT be possible to add the zero address to the
ContractsRegistry. - The
ContractsRegistryMUST use theIDependantinterface in theinjectDependenciesandinjectDependenciesWithDatamethods.
Dependant
The Dependant contract is the one that depends on other contracts present in the system. In order to support dependency injection mechanism, the dependant contract MUST implement the following interface:
pragma solidity ^0.8.0;
interface IDependant {
/**
* @notice The function that is called from the ContractsRegistry (or factory) to inject dependencies.
* @param contractsRegistry the registry to pull dependencies from
* @param data the extra data that might provide additional application-specific context/behavior
*
* The Dependant MUST add a dependency injector access check to this method
*/
function setDependencies(address contractsRegistry, bytes calldata data) external;
/**
* @notice The function that sets the new dependency injector.
* @param injector the new dependency injector
*
* The Dependant MUST add a dependency injector access check to this method
*/
function setInjector(address injector) external;
/**
* @notice The function that gets the current dependency injector
* @return the current dependency injector
*/
function getInjector() external view returns (address);
}
- The
Dependantcontract MUST pull its dependencies in thesetDependenciesmethod from the passedcontractsRegistryaddress. - The
Dependantcontract MAY store the dependency injector address in the special slot0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583(obtained asbytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)).
Rationale
There are a few design decisions that have to be specified explicitly:
ContractsRegistry Rationale
Usage
The extensions of this EIP SHOULD add proper access control checks to the described non-view methods.
The getContract and getImplementation methods MUST revert if the nonexistent contracts are queried.
The ContractsRegistry MAY be set behind the proxy to enable runtime addition of custom methods. Applications MAY also leverage the pattern to develop custom tree-like ContractsRegistry data structures.
Contracts identifier
The string contracts identifier is chosen over the uint256 and bytes32 to maintain code readability and reduce the human-error chances when interacting with the ContractsRegistry. Being the topmost smart contract, it MAY be typical for the users to interact with it via block explorers or DAOs. Clarity was prioritized over gas usage.
Proxy
The Transparent proxy is chosen over the UUPS proxy to hand the upgradeability responsibility to the ContractsRegistry itself. The extensions of this EIP MAY use the proxy of their choice.
Dependant Rationale
Dependencies
The required dependencies MUST be set in the overridden setDependencies method, not in the constructor or initializer methods.
The data parameter is provided to carry additional application-specific context. It MAY be used to extend the method’s behavior.
Injector
Only the injector MUST be able to call the setDependencies and setInjector methods. The initial injector will be a zero address, in that case, the call MUST NOT revert on access control checks. The setInjector function is made external to support the dependency injection mechanism for factory-made contracts. However, the method SHOULD be used with extra care.
The injector address MAY be stored in the dedicated slot 0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583 to exclude the chances of storage collision.
Reference Implementation
0xdistributedlab-solidity-library dev-modules provides a reference implementation.
Security Considerations
The described EIP must be used with extra care as the loss/leakage of credentials to the ContractsRegistry leads to the application’s point of no return. The ContractRegistry is a cornerstone of the protocol, access must be granted to the trusted parties only.
ContractsRegistry Security Considerations
- The non-view methods of
ContractsRegistrycontract MUST be overridden with proper access control checks. - The
ContractsRegistrydoes not perform any upgradeability checks between the proxy upgrades. It is the user’s responsibility to make sure that the new implementation is compatible with the old one.
Dependant Security Considerations
- The non-view methods of
Dependantcontract MUST be overridden with proper access control checks. Only the dependency injector MUST be able to call them. - The
Dependantcontract MUST set its dependency injector no later than the first call to thesetDependenciesfunction is made. That being said, it is possible to front-run the first dependency injection.
