Skip to main content

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)
InputTypeDescription
daoaddressThe address of the DAO to which the plugin belongs.
calleraddressThe address (EOA or contract) that requested the application of a setup on the associated DAO.
permissionIdbytes32The 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)
InputTypeDescription
pluginaddressThe 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)
InputTypeDescription
proxyaddressThe address of the proxy.
implementationaddressThe address of the implementation contract.
initDatabytesThe 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)
InputTypeDescription
pluginaddressThe 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)
InputTypeDescription
preparedSetupIdbytes32The 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)
InputTypeDescription
preparedSetupIdbytes32The prepared setup ID.

error InvalidUpdateVersion

Thrown if the update version is invalid.

error InvalidUpdateVersion(struct PluginRepo.Tag currentVersionTag, struct PluginRepo.Tag newVersionTag)
InputTypeDescription
currentVersionTagstruct PluginRepo.TagThe tag of the current version to update from.
newVersionTagstruct PluginRepo.TagThe 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)
InputTypeDescription
currentAppliedSetupIdbytes32The current applied setup ID with which the data in the supplied payload must match.
appliedSetupIdbytes32The 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)
InputTypeDescription
senderaddressThe sender that prepared the plugin installation.
daoaddressThe address of the DAO to which the plugin belongs.
preparedSetupIdbytes32The prepared setup ID obtained from the supplied data.
pluginSetupRepocontract PluginRepoThe repository storing the PluginSetup contracts of all versions of a plugin.
versionTagstruct PluginRepo.TagThe version tag of the plugin setup of the prepared installation.
databytesThe bytes-encoded data containing the input parameters for the preparation as specified in the corresponding ABI on the version's metadata.
pluginaddressThe address of the plugin contract.
preparedSetupDatastruct IPluginSetup.PreparedSetupDataThe 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)
InputTypeDescription
daoaddressThe address of the DAO to which the plugin belongs.
pluginaddressThe address of the plugin contract.
preparedSetupIdbytes32The prepared setup ID.
appliedSetupIdbytes32The 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)
InputTypeDescription
senderaddressThe sender that prepared the plugin update.
daoaddressThe address of the DAO to which the plugin belongs.
preparedSetupIdbytes32The prepared setup ID.
pluginSetupRepocontract PluginRepoThe repository storing the PluginSetup contracts of all versions of a plugin.
versionTagstruct PluginRepo.TagThe version tag of the plugin setup of the prepared update.
setupPayloadstruct IPluginSetup.SetupPayloadThe 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.
preparedSetupDatastruct IPluginSetup.PreparedSetupDataThe deployed plugin's relevant data which consists of helpers and permissions.
initDatabytesThe 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)
InputTypeDescription
daoaddressThe address of the DAO to which the plugin belongs.
pluginaddressThe address of the plugin contract.
preparedSetupIdbytes32The prepared setup ID.
appliedSetupIdbytes32The 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)
InputTypeDescription
senderaddressThe sender that prepared the plugin uninstallation.
daoaddressThe address of the DAO to which the plugin belongs.
preparedSetupIdbytes32The prepared setup ID.
pluginSetupRepocontract PluginRepoThe repository storing the PluginSetup contracts of all versions of a plugin.
versionTagstruct PluginRepo.TagThe version tag of the plugin to used for install preparation.
setupPayloadstruct IPluginSetup.SetupPayloadThe 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.
permissionsstruct 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)
InputTypeDescription
daoaddressThe address of the DAO to which the plugin belongs.
pluginaddressThe address of the plugin contract.
preparedSetupIdbytes32The 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)
InputTypeDescription
_daoaddressThe address of the DAO.
_permissionIdbytes32The permission identifier.

public function constructor

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

constructor(contract PluginRepoRegistry _repoRegistry) public
InputTypeDescription
_repoRegistrycontract PluginRepoRegistryThe 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)
InputTypeDescription
_daoaddressThe address of the installing DAO.
_paramsstruct PluginSetupProcessor.PrepareInstallationParamsThe struct containing the parameters for the prepareInstallation function.
Output
pluginaddressThe prepared plugin contract address.
preparedSetupDatastruct IPluginSetup.PreparedSetupDataThe 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
InputTypeDescription
_daoaddressThe address of the installing DAO.
_paramsstruct PluginSetupProcessor.ApplyInstallationParamsThe 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)
InputTypeDescription
_daoaddressThe address of the DAO For which preparation of update happens.
_paramsstruct PluginSetupProcessor.PrepareUpdateParamsThe struct containing the parameters for the prepareUpdate function.
Output
initDatabytesThe initialization data to be passed to upgradeable contracts when the update is applied
preparedSetupDatastruct IPluginSetup.PreparedSetupDataThe 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
InputTypeDescription
_daoaddressThe address of the updating DAO.
_paramsstruct PluginSetupProcessor.ApplyUpdateParamsThe 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)
InputTypeDescription
_daoaddressThe address of the uninstalling DAO.
_paramsstruct PluginSetupProcessor.PrepareUninstallationParamsThe struct containing the parameters for the prepareUninstallation function.
Output
permissionsstruct 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
InputTypeDescription
_daoaddressThe address of the DAO.
_paramsstruct PluginSetupProcessor.ApplyUninstallationParamsThe 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
InputTypeDescription
pluginInstallationIdbytes32The plugin installation ID obtained from the hash of abi.encode(daoAddress, pluginAddress).
preparedSetupIdbytes32The 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.

© 2024