Admin

The Defender Admin service acts as an interface to manage your smart contract project through secure multisig contracts or timelocks. Defender Admin holds no control at all over your system, which is fully controlled by the keys of the signers.

Use cases

Use Defender Admin whenever you need secure management of your smart contracts on-chain. Any administrative operation should not be unilaterally controlled by a single owner. Instead, set up a multi-signature wallet and rely on Defender Admin to run any of the following actions through it:

  • Upgrading a contract to a new implementation

  • Tweaking a numerical parameter in your protocol that affects its behavior

  • Managing an access control list for restricted operations

  • Pausing your contract in the event of an emergency

Contracts and Proposals

To begin managing one of your Contracts in Defender Admin, the first step is to register it. This is a one-time process where you specify network and address and assign a name to your contract. The contract’s ABI will be automatically pulled in from etherscan or sourcify if it has been verified, but you will need to manually enter it otherwise.

Defender Admin Edit Contract
Defender Admin will automatically attempt to detect some features of your contract. Today, it will detect whether it’s an EIP1967-compatible or a legacy zOS proxy (and load the implementation’s ABI in that case) and whether it’s managed by a ProxyAdmin contract.
Defender Admin Withdraw

Once the contract has been added, you can create new Proposals for it. Each proposal is an action you will want to execute on the contract, which is executed via a multisig contract, and requires a quorum of admins to be in agreement. Once created, other admins can review and approve the proposal until it reaches the approval threshold and is executed.

Alternatively, you can also choose to execute an action directly on a Contract using Admin, if the function is not restricted to be called via a multisig.

When creating a new proposal, Defender Admin will first simulate it and will refuse to create it if the action reverts, showing the revert reason returned by the contract.

API Access

You can programmatically add contracts to your Admin dashboard and create new proposals via the Defender Admin API. Check out the defender-admin-client npm package for more info.

Proposal types

Defender Admin supports three kinds of proposals today: upgrades, pause and custom actions. More proposal types will be added down the road.

Upgrades

An upgrade action can only be executed on EIP1967-compatible or legacy zOS upgradeable proxies that expose an upgradeTo(address) function. Defender Admin will handle proxies directly owned by a multi-signature wallet or proxies managed by a ProxyAdmin that is in turn owned by the wallet. The upgrade action only requires you to choose the new implementation address, and Defender Admin takes care of the rest.

Defender Admin currently does not validate storage layout compatibility of the implementations. For this reason, we strongly suggest using the prepareUpgrade function from the openzeppelin-upgrades library, via truffle or buidler, to deploy the target implementation.

Pause/Unpause

A pause action can be executed on contracts whose ABI exposes a pause() function. If the ABI also exposes an unpause() function, Defender Admin will also let you execute unpause actions. Both the pause and the unpause actions only require you to specify which Admin account they should be executed through.

If, additionally, your contract ABI exposes a paused() or isPaused() function returning a boolean result, Defender will query it and show you its status in the contract’s dashboard page, as seen in the image below.

Defender Admin Paused Contract

Custom actions

A custom action is a call to any function in the managed contract. Defender Admin will handle the encoding of the transaction data and submit it as a new proposal via the chosen multi-signature wallet.

If no multi-signature wallet is specified, Defender will send the transaction directly to the contract.

Custom actions can also be repeated, which will present you to a pre-filled form, so you can review and tweak the action before approving it.

Certain ABI types, such as nested structs, are not yet supported. Contact us if you need to call a function that is currently unsupported!

Multi-signature wallets

Defender Admin supports two kinds of multi-signature wallets: Gnosis Safe and Gnosis MultisigWallet. If you are using a multi-signature implementation that is not supported, let us know!

Gnosis Safe

The Gnosis Safe wallet gathers offline signatures of each admin and then submits a single transaction with all signatures to execute the action. To share signatures, it relies on the Safe Transaction Service hosted by Gnosis.

The Safe Transaction Service is only available on Mainnet, xDai, BSC, and Rinkeby. Still, you can use Defender Admin on any network; it will just skip syncing with the transaction service if it’s not available.

When using a Gnosis Safe, Defender Admin will synchronize all signatures to and from the Safe Transaction Service. This way, any admins on your team using the Safe UI will still be able to sign the Defender Admin proposals.

The Safe contract requires all its proposals to be executed in order. If you have gathered all signatures for a proposal and still cannot execute it, make sure there are no prior proposals pending execution.

Gnosis Safe wallets also allow executing DELEGATECALL`s into other contracts, in order to execute arbitrary code in the context of the multisig. You can currently create an Admin action proposal to issue a delegate call via the API using the `defender-admin-client.

Gnosis MultisigWallet

The Gnosis MultisigWallet requires each admin to submit a new transaction with their approval, so there is no need for a separate service to coordinate.

In addition to the vanilla MultisigWallet, Defender Admin also supports a PartiallyDelayedMultisig variant developed by dYdX. In this wallet, once a proposal has been approved, it is required to wait for a timelock period before it can be executed. Defender Admin will load this information from the contract and display it on the interface.

Managing your multi-sig from Defender Admin

Creating a Gnosis Safe multisig from Defender

You can create and deploy a new Gnosis Safe multisig wallet directly from Defender. This comes especially handy in networks where the official Gnosis Safe UI is not yet available. To create a new Gnosis Safe, go to Admin and click on "Contracts" and then "Create Gnosis Safe". You’ll be taken to a simple form where you will be asked to provide the initial list of owners and threshold for the multisig. That’s it!

Modifying your multisig settings from Defender

You can modify your multisig settings by creating custom action proposals to execute management functions addOwner or changeThreshold, as you would with any other contract you import to Defender.

Defender Admin Add Owner

Timelocks

Creating a Timelock Controller from Defender

You can create and deploy a new Timelock Controller directly from Defender. To create a new Timelock, go to Admin and click on "Contracts" and then "Create timelock". You’ll be taken to a simple form where you will be asked to provide the initial list of proposers and executors as well as the minimum delay for a proposal to be executed.

In order to verify the contract on etherscan, you can find the source code and compiler settings below:

The compiler settings to deploy the contract:

solidity: {
    version: "0.8.4",
    settings: {
        optimizer: {
            enabled: true,
            runs: 200
        }
    }
}

Creating timelocked proposals

Defender Admin supports timelocked admin proposals via the TimelockController contract provided by the OpenZeppelin Contracts library.

To execute a timelocked proposal, you need:

  1. A multisig (or EOA) that’s a proposer in a TimelockController.

  2. A TimelockController with rights over the action you want to run on your contract.

Once proper permissions are in place, just create a proposal as you normally would, ticking the Timelock checkbox in the Execution strategy section. Then enter your timelock’s address and choose the minimum delay between the proposal’s approval and its execution.

Configuring a proposal’s timelock

Notice that you can create a timelocked proposal regardless of whether it is approved through a multisig or an EOA. Any approval policy should work provided the right on-chain permission structure is in place.

Creating a timelocked proposal to be approved through a Gnosis Safe

Managing timelocked proposals

Once you created a timelocked proposal, Defender will guide you and your collaborators to see it through. Assuming you chose to approve the proposal through a Gnosis Safe, the steps from proposal creation to the underlying admin action’s execution are:

  1. Collect enough multisig owner approvals (as dictated by the multisig’s current configuration).

  2. Schedule the action, with the specified delay period. Keep in mind the multisig in use needs to be a proposer in the TimelockController contract. Read more here.

  3. After the specified delay period ends, execute the action. It is worth noting here that the EOA that executes this action needs to be an executor in the TimelockController contract.

Currently Defender does not support timelocked Upgrade proposals. That capability is a work in progress and we plan release it soon.

Governance

You can also delegate control of an Admin proposal to a Governor contract. To create a Governor proposal, simply set the execution strategy to Governor and enter a valid Governor contract address. Defender will perform basic checks to validate that the contract actually conforms to the Governor interface before letting you proceed.

Defender Admin supports creating proposals on OpenZeppelin’s Governor contract, as well as Compound’s Alpha and Bravo dialects.

Create a proposal to be managed by a Governor

Once you entered these details, Defender will let you send the proposal to the Governor contract.

Send proposal to the Governor

From then on, your community can use any Governor compatible voting DApp (such as Tally). Defender will track the state of the proposal each time you open it.

Defender tracks the state of your proposal by querying the Governor

Wallets

All approvals in Defender Admin today are handled via Metamask. Defender Admin also supports hardware wallets through Metamask. We have so far tested support with Ledger Nano. Please contact us if you want to use a different wallet (software or hardware) with Defender.

Address book

All members of your team share an address book where you can define user-friendly names for your accounts or contracts. You can set up these names anywhere you see an address in Defender just by clicking on it, or you can manage your entire address book in the corresponding section in the top-right user menu. Defender will also automatically create address book entries for you when you import a new contract into Admin.

Defender Admin Edit Address

Defender will also source information from the address book whenever you are required to enter an address, so you can easily fetch addresses from your address book for creating new proposals or sending transactions.

Defender Admin Address Input

Security considerations

Defender Admin acts exclusively as an interface to your contracts and multi-signature wallets. This means that you do not grant Defender any rights over your contracts by using Admin to manage them. All proposal approvals are signed client-side using the admin user private key through Metamask. The Defender Admin backend is only involved in storing proposal metadata and sharing the approval signatures when these are not stored on-chain. Ultimately, the multi-signature wallet contracts are the ones that verify these approvals and execute the proposed actions.

Defender Admin’s main contribution to security is then related to usability. First, it automates the process of crafting the transaction for a proposal to avoid manual errors. Second, it provides a clear interface for reviewing a proposal without having to manually decode the proposal hex data.

Coming up…​

We are working on a number of enhancements to let you better navigate and organize your contracts; public views for contracts, so you can optionally share with your community what change proposals are coming; first class support for access control in contracts; and governance. Stay tuned, and let us know if you have any requests!