PluginSetupProcessor

Description

This contract processes the preparation and application of plugin setups (installation, update, uninstallation) on behalf of a requesting DAO.

This contract is temporarily granted the ROOT_PERMISSION_ID permission on the applying DAO and therefore is highly security critical.

Implementation

public variable APPLY_INSTALLATION_PERMISSION_ID

The ID of the permission required to call the applyInstallation function.

bytes32 APPLY_INSTALLATION_PERMISSION_ID

public variable APPLY_UPDATE_PERMISSION_ID

The ID of the permission required to call the applyUpdate function.

bytes32 APPLY_UPDATE_PERMISSION_ID

public variable APPLY_UNINSTALLATION_PERMISSION_ID

The ID of the permission required to call the applyUninstallation function.

bytes32 APPLY_UNINSTALLATION_PERMISSION_ID

public struct PluginState

struct PluginState {
  uint256 blockNumber;
  bytes32 currentAppliedSetupId;
  mapping(bytes32 => uint256) preparedSetupIdToBlockNumber;
}

public variable states

A mapping between the plugin installation ID (obtained from the DAO and plugin address) and the plugin state information.

mapping(bytes32 => struct PluginSetupProcessor.PluginState) states

This variable is public on purpose to allow future versions to access and migrate the storage.

public struct PrepareInstallationParams

struct PrepareInstallationParams {
  struct PluginSetupRef pluginSetupRef;
  bytes data;
}

public struct ApplyInstallationParams

struct ApplyInstallationParams {
  struct PluginSetupRef pluginSetupRef;
  address plugin;
  struct PermissionLib.MultiTargetPermission[] permissions;
  bytes32 helpersHash;
}

public struct PrepareUpdateParams

struct PrepareUpdateParams {
  struct PluginRepo.Tag currentVersionTag;
  struct PluginRepo.Tag newVersionTag;
  contract PluginRepo pluginSetupRepo;
  struct IPluginSetup.SetupPayload setupPayload;
}

public struct ApplyUpdateParams

struct ApplyUpdateParams {
  address plugin;
  struct PluginSetupRef pluginSetupRef;
  bytes initData;
  struct PermissionLib.MultiTargetPermission[] permissions;
  bytes32 helpersHash;
}

public struct PrepareUninstallationParams

struct PrepareUninstallationParams {
  struct PluginSetupRef pluginSetupRef;
  struct IPluginSetup.SetupPayload setupPayload;
}

public struct ApplyUninstallationParams

struct ApplyUninstallationParams {
  address plugin;
  struct PluginSetupRef pluginSetupRef;
  struct PermissionLib.MultiTargetPermission[] permissions;
}

public variable repoRegistry

The plugin repo registry listing the PluginRepo contracts versioning the PluginSetup contracts.

contract PluginRepoRegistry repoRegistry

error SetupApplicationUnauthorized

Thrown if a setup is unauthorized and cannot be applied because of a missing permission of the associated DAO.

error SetupApplicationUnauthorized(address dao, address caller, bytes32 permissionId)

Input	Type	Description
dao	address	The address of the DAO to which the plugin belongs.
caller	address	The address (EOA or contract) that requested the application of a setup on the associated DAO.
permissionId	bytes32	The permission identifier.

This is thrown if the APPLY_INSTALLATION_PERMISSION_ID, APPLY_UPDATE_PERMISSION_ID, or APPLY_UNINSTALLATION_PERMISSION_ID is missing.

error PluginNonupgradeable

Thrown if a plugin is not upgradeable.

error PluginNonupgradeable(address plugin)

Input	Type	Description
plugin	address	The address of the plugin contract.

error PluginProxyUpgradeFailed

Thrown if the upgrade of an UUPSUpgradeable proxy contract (see ERC-1822) failed.

error PluginProxyUpgradeFailed(address proxy, address implementation, bytes initData)

Input	Type	Description
proxy	address	The address of the proxy.
implementation	address	The address of the implementation contract.
initData	bytes	The initialization data to be passed to the upgradeable plugin contract via upgradeToAndCall.

error IPluginNotSupported

Thrown if a contract does not support the IPlugin interface.

error IPluginNotSupported(address plugin)

Input	Type	Description
plugin	address	The address of the contract.

error PluginRepoNonexistent

Thrown if a plugin repository does not exist on the plugin repo registry.

error PluginRepoNonexistent()

error SetupAlreadyPrepared

Thrown if a plugin setup was already prepared indicated by the prepared setup ID.

error SetupAlreadyPrepared(bytes32 preparedSetupId)

Input	Type	Description
preparedSetupId	bytes32	The prepared setup ID.

error SetupNotApplicable

Thrown if a prepared setup ID is not eligible to be applied. This can happen if another setup has been already applied or if the setup wasn't prepared in the first place.

error SetupNotApplicable(bytes32 preparedSetupId)

Input	Type	Description
preparedSetupId	bytes32	The prepared setup ID.

error InvalidUpdateVersion

Thrown if the update version is invalid.

error InvalidUpdateVersion(struct PluginRepo.Tag currentVersionTag, struct PluginRepo.Tag newVersionTag)

Input	Type	Description
currentVersionTag	struct PluginRepo.Tag	The tag of the current version to update from.
newVersionTag	struct PluginRepo.Tag	The tag of the new version to update to.

error PluginAlreadyInstalled

Thrown if plugin is already installed and one tries to prepare or apply install on it.

error PluginAlreadyInstalled()

error InvalidAppliedSetupId

Thrown if the applied setup ID resulting from the supplied setup payload does not match with the current applied setup ID.

error InvalidAppliedSetupId(bytes32 currentAppliedSetupId, bytes32 appliedSetupId)

Input	Type	Description
currentAppliedSetupId	bytes32	The current applied setup ID with which the data in the supplied payload must match.
appliedSetupId	bytes32	The applied setup ID obtained from the data in the supplied setup payload.

event InstallationPrepared

Emitted with a prepared plugin installation to store data relevant for the application step.

event InstallationPrepared(address sender, address dao, bytes32 preparedSetupId, contract PluginRepo pluginSetupRepo, struct PluginRepo.Tag versionTag, bytes data, address plugin, struct IPluginSetup.PreparedSetupData preparedSetupData)

Input	Type	Description
sender	address	The sender that prepared the plugin installation.
dao	address	The address of the DAO to which the plugin belongs.
preparedSetupId	bytes32	The prepared setup ID obtained from the supplied data.
pluginSetupRepo	contract PluginRepo	The repository storing the PluginSetup contracts of all versions of a plugin.
versionTag	struct PluginRepo.Tag	The version tag of the plugin setup of the prepared installation.
data	bytes	The bytes-encoded data containing the input parameters for the preparation as specified in the corresponding ABI on the version's metadata.
plugin	address	The address of the plugin contract.
preparedSetupData	struct IPluginSetup.PreparedSetupData	The deployed plugin's relevant data which consists of helpers and permissions.

event InstallationApplied

Emitted after a plugin installation was applied.

event InstallationApplied(address dao, address plugin, bytes32 preparedSetupId, bytes32 appliedSetupId)

Input	Type	Description
dao	address	The address of the DAO to which the plugin belongs.
plugin	address	The address of the plugin contract.
preparedSetupId	bytes32	The prepared setup ID.
appliedSetupId	bytes32	The applied setup ID.

event UpdatePrepared

Emitted with a prepared plugin update to store data relevant for the application step.

event UpdatePrepared(address sender, address dao, bytes32 preparedSetupId, contract PluginRepo pluginSetupRepo, struct PluginRepo.Tag versionTag, struct IPluginSetup.SetupPayload setupPayload, struct IPluginSetup.PreparedSetupData preparedSetupData, bytes initData)

Input	Type	Description
sender	address	The sender that prepared the plugin update.
dao	address	The address of the DAO to which the plugin belongs.
preparedSetupId	bytes32	The prepared setup ID.
pluginSetupRepo	contract PluginRepo	The repository storing the PluginSetup contracts of all versions of a plugin.
versionTag	struct PluginRepo.Tag	The version tag of the plugin setup of the prepared update.
setupPayload	struct IPluginSetup.SetupPayload	The payload containing the plugin and helper contract addresses deployed in a preparation step as well as optional data to be consumed by the plugin setup.
preparedSetupData	struct IPluginSetup.PreparedSetupData	The deployed plugin's relevant data which consists of helpers and permissions.
initData	bytes	The initialization data to be passed to the upgradeable plugin contract.

event UpdateApplied

Emitted after a plugin update was applied.

event UpdateApplied(address dao, address plugin, bytes32 preparedSetupId, bytes32 appliedSetupId)

Input	Type	Description
dao	address	The address of the DAO to which the plugin belongs.
plugin	address	The address of the plugin contract.
preparedSetupId	bytes32	The prepared setup ID.
appliedSetupId	bytes32	The applied setup ID.

event UninstallationPrepared

Emitted with a prepared plugin uninstallation to store data relevant for the application step.

event UninstallationPrepared(address sender, address dao, bytes32 preparedSetupId, contract PluginRepo pluginSetupRepo, struct PluginRepo.Tag versionTag, struct IPluginSetup.SetupPayload setupPayload, struct PermissionLib.MultiTargetPermission[] permissions)

Input	Type	Description
sender	address	The sender that prepared the plugin uninstallation.
dao	address	The address of the DAO to which the plugin belongs.
preparedSetupId	bytes32	The prepared setup ID.
pluginSetupRepo	contract PluginRepo	The repository storing the PluginSetup contracts of all versions of a plugin.
versionTag	struct PluginRepo.Tag	The version tag of the plugin to used for install preparation.
setupPayload	struct IPluginSetup.SetupPayload	The payload containing the plugin and helper contract addresses deployed in a preparation step as well as optional data to be consumed by the plugin setup.
permissions	struct PermissionLib.MultiTargetPermission[]	The list of multi-targeted permission operations to be applied to the installing DAO.

event UninstallationApplied

Emitted after a plugin installation was applied.

event UninstallationApplied(address dao, address plugin, bytes32 preparedSetupId)

Input	Type	Description
dao	address	The address of the DAO to which the plugin belongs.
plugin	address	The address of the plugin contract.
preparedSetupId	bytes32	The prepared setup ID.

internal modifier canApply

A modifier to check if a caller has the permission to apply a prepared setup.

modifier canApply(address _dao, bytes32 _permissionId)

Input	Type	Description
_dao	address	The address of the DAO.
_permissionId	bytes32	The permission identifier.

public function constructor

Constructs the plugin setup processor by setting the associated plugin repo registry.

constructor(contract PluginRepoRegistry _repoRegistry) public

Input	Type	Description
_repoRegistry	contract PluginRepoRegistry	The plugin repo registry contract.

external function prepareInstallation

Prepares the installation of a plugin.

function prepareInstallation(address _dao, struct PluginSetupProcessor.PrepareInstallationParams _params) external returns (address plugin, struct IPluginSetup.PreparedSetupData preparedSetupData)

Input	Type	Description
_dao	address	The address of the installing DAO.
_params	struct PluginSetupProcessor.PrepareInstallationParams	The struct containing the parameters for the prepareInstallation function.
Output
plugin	address	The prepared plugin contract address.
preparedSetupData	struct IPluginSetup.PreparedSetupData	The data struct containing the array of helper contracts and permissions that the setup has prepared.

external function applyInstallation

Applies the permissions of a prepared installation to a DAO.

function applyInstallation(address _dao, struct PluginSetupProcessor.ApplyInstallationParams _params) external

Input	Type	Description
_dao	address	The address of the installing DAO.
_params	struct PluginSetupProcessor.ApplyInstallationParams	The struct containing the parameters for the applyInstallation function.

external function prepareUpdate

Prepares the update of an UUPS upgradeable plugin.

function prepareUpdate(address _dao, struct PluginSetupProcessor.PrepareUpdateParams _params) external returns (bytes initData, struct IPluginSetup.PreparedSetupData preparedSetupData)

Input	Type	Description
_dao	address	The address of the DAO For which preparation of update happens.
_params	struct PluginSetupProcessor.PrepareUpdateParams	The struct containing the parameters for the prepareUpdate function.
Output
initData	bytes	The initialization data to be passed to upgradeable contracts when the update is applied
preparedSetupData	struct IPluginSetup.PreparedSetupData	The data struct containing the array of helper contracts and permissions that the setup has prepared.

The list of _params.setupPayload.currentHelpers has to be specified in the same order as they were returned from previous setups preparation steps (the latest prepareInstallation or prepareUpdate step that has happend) on which the update is prepared for.

external function applyUpdate

Applies the permissions of a prepared update of an UUPS upgradeable proxy contract to a DAO.

function applyUpdate(address _dao, struct PluginSetupProcessor.ApplyUpdateParams _params) external

Input	Type	Description
_dao	address	The address of the updating DAO.
_params	struct PluginSetupProcessor.ApplyUpdateParams	The struct containing the parameters for the applyUpdate function.

external function prepareUninstallation

Prepares the uninstallation of a plugin.

function prepareUninstallation(address _dao, struct PluginSetupProcessor.PrepareUninstallationParams _params) external returns (struct PermissionLib.MultiTargetPermission[] permissions)

Input	Type	Description
_dao	address	The address of the uninstalling DAO.
_params	struct PluginSetupProcessor.PrepareUninstallationParams	The struct containing the parameters for the prepareUninstallation function.
Output
permissions	struct PermissionLib.MultiTargetPermission[]	The list of multi-targeted permission operations to be applied to the uninstalling DAO.

The list of _params.setupPayload.currentHelpers has to be specified in the same order as they were returned from previous setups preparation steps (the latest prepareInstallation or prepareUpdate step that has happend) on which the uninstallation was prepared for.

external function applyUninstallation

Applies the permissions of a prepared uninstallation to a DAO.

function applyUninstallation(address _dao, struct PluginSetupProcessor.ApplyUninstallationParams _params) external

Input	Type	Description
_dao	address	The address of the DAO.
_params	struct PluginSetupProcessor.ApplyUninstallationParams	The struct containing the parameters for the applyUninstallation function.

The list of _params.setupPayload.currentHelpers has to be specified in the same order as they were returned from previous setups preparation steps (the latest prepareInstallation or prepareUpdate step that has happend) on which the uninstallation was prepared for.

public function validatePreparedSetupId

Validates that a setup ID can be applied for applyInstallation, applyUpdate, or applyUninstallation.

function validatePreparedSetupId(bytes32 pluginInstallationId, bytes32 preparedSetupId) public view

Input	Type	Description
pluginInstallationId	bytes32	The plugin installation ID obtained from the hash of abi.encode(daoAddress, pluginAddress).
preparedSetupId	bytes32	The prepared setup ID to be validated.

If the block number stored in states[pluginInstallationId].blockNumber exceeds the one stored in pluginState.preparedSetupIdToBlockNumber[preparedSetupId], the prepared setup with preparedSetupId is outdated and not applicable anymore.