Controller

The Controller is the single source of truth for user positions. It holds the canonical state of all vault deposits, debt balances, and collateral values. This prevents state inconsistencies that can arise from direct interactions with underlying protocols.

• Enforces atomicity: All state updates (deposit, borrow, withdraw) happen in a single transaction.
• Simplifies integrations: External systems (oracles, keepers) query a single contract for user health.

It exposes a standardized, public interface (API) for all user actions. Users and integrators interact only with the Controller, not the underlying lending pools or yield strategies directly.

• Standardized functions: Common patterns like deposit(), borrow(), withdraw().
• Access control: Can implement whitelists for certain actions while remaining open for general use.
• Example: In a lending protocol, you call controller.borrow(asset, amount) instead of interacting with the pool contract.

The Controller executes liquidation logic and collateral factor checks before any state-changing operation. It protects the protocol by ensuring positions remain solvent.

• Pre-transaction validation: Checks Loan-to-Value (LTV) ratios before allowing a borrow or withdrawal.
• Liquidation trigger: Identifies undercollateralized positions and allows liquidators to call a liquidate() function.
• Price oracle integration: Pulls real-time prices to calculate accurate collateral values.

It abstracts away the complexity of underlying yield-generating strategies (e.g., LP staking, lending markets). Users deposit into a vault, and the Controller handles the strategy execution.

• Single asset vaults: User deposits USDC, Controller deploys it to multiple strategies (Aave, Compound, Uniswap).
• Harvesting automation: Often coordinates with keeper bots to claim and compound rewards.
• Upgradability: Allows strategy logic to be changed without migrating user funds.

The Controller is responsible for calculating, deducting, and routing protocol fees. This is a core mechanism for protocol revenue and tokenomics.

• Fee types: Can include performance fees (on yield), withdrawal fees, or origination fees (on borrow).
• Treasury routing: Automatically sends accrued fees to a designated treasury or fee distributor contract.
• Transparent accounting: Fee events are logged on-chain, visible to all users.

Controllers are often built with proxy patterns (e.g., Transparent or UUPS) to allow for upgrades via governance. The logic can be improved without changing the contract address users interact with.

• Governance control: A DAO or multi-sig typically holds upgrade permissions.
• Minimized disruption: User positions and approvals persist through upgrades.
• Security trade-off: Requires extreme trust in governance, as a malicious upgrade could compromise all funds.

A controller is an entity (person, organization, or autonomous software) that possesses the cryptographic keys or other mechanisms required to update a DID document. This authority is distinct from the subject of the DID, which is the entity the identifier describes. The controller can:

• Add or rotate verification methods (e.g., public keys).
• Update service endpoints for interaction.
• Delegate authority to other controllers.
• Deactivate the DID entirely. This separation allows for flexible management models, such as a parent company controlling employee DIDs.

Simple DID methods often have an implicit 1:1 relationship between subject and controller.

• did:key: The controller is the holder of the private key corresponding to the public key embedded directly in the DID itself. Control is self-sovereign and non-updatable; a new DID must be created to change keys.
• did:web: Control is asserted by whoever controls the web domain and path specified in the DID. Updates are made by publishing a new DID document to that HTTPS endpoint. This delegates control to the domain's administrator.

Blockchain-based methods enable sophisticated, on-chain controller management.

• did:ethr (Ethereum): The controller is the Ethereum account that owns the smart contract or registry entry for the DID. Control can be transferred by:
  • Sending a transaction from the current controller account.
  • Using a delegate key, which can be assigned limited permissions.
• This model allows for multi-sig control, key rotation without DID change, and recovery mechanisms through smart contract logic.

A critical design pattern is separating the subject (who the DID is about) from the controller (who manages it).

• Example: A corporate DID (subject = the company) might be managed by a board using a multi-sig wallet (controllers).
• Example: A device DID (subject = IoT sensor) might be controlled by a management service.
• The controller property in a DID document can list one or more DIDs that have authority, enabling complex trust hierarchies and custodial scenarios.

Controllers exercise authority through capability invocation keys. The DID document's verificationMethod section lists keys, each with a purpose.

• authentication: Proves the subject/controller for signing into systems.
• assertionMethod: Signs Verifiable Credentials.
• capabilityInvocation: Authorizes changes to the DID document itself (the controller's key).
• capabilityDelegation: Delegates authority to other keys. Only keys with the capabilityInvocation relationship are used to sign updates, enforcing a clear authorization model.

Robust DID methods provide mechanisms for controllers to recover from key loss.

• Pre-defined Recovery Controllers: A separate DID or list of DIDs can be specified in the document with sole power to replace the primary controller in a disaster scenario.
• Time-Locked Operations: Some methods allow setting a delay on controller changes, providing a window to cancel unauthorized attempts.
• Social Recovery: Using techniques like shamir's secret sharing among trusted parties or multi-sig guardians. The choice of recovery model is a fundamental security trade-off for the controller.

A Controller often represents a centralization vector, creating a single point of failure or censorship. If the Controller's private keys are compromised, an attacker can execute privileged functions. This risk is mitigated through multi-signature wallets (e.g., Gnosis Safe) or decentralized autonomous organization (DAO) governance, which distribute control among multiple parties.

Controllers typically have the authority to execute high-risk functions, which defines the protocol's attack surface. Common privileges include:

• Minting/Burning tokens (e.g., in upgradeable ERC-20 contracts).
• Pausing contract functionality in emergencies.
• Upgrading contract logic via a proxy pattern.
• Changing critical parameters like fees or rewards. Each function is a potential target for exploitation if access is breached.

A key security practice is implementing a time-lock on Controller actions. This introduces a mandatory delay (e.g., 24-72 hours) between a proposal's submission and its execution. This allows users and the community to:

• Review pending changes for malicious code.
• Exit the system if they disagree with the action.
• Serve as a critical circuit-breaker against rushed or malicious governance proposals.

To achieve full decentralization, a Controller can renounce its privileges, often by calling a function like renounceOwnership(). This action:

• Transfers control to a zero address, making the contract immutable.
• Permanently removes the ability to upgrade, pause, or mint.
• Is irreversible and should only be done after extensive auditing and when the protocol is deemed complete and secure.

Many protocols use a proxy pattern (e.g., Transparent or UUPS) where a Controller manages a logic contract upgrade. Security considerations include:

• The proxy admin is a powerful Controller role.
• Risks of storage collisions during upgrades.
• The potential for a malicious upgrade to drain all funds.
• Best practice is to use audited, standard implementations like OpenZeppelin's upgradeable contracts.

Secure management of the Controller's private keys is paramount. Best practices involve:

• Using hardware security modules (HSMs) or multi-party computation (MPC) wallets for enterprise-grade security.
• Avoiding storing private keys on internet-connected machines.
• Establishing clear off-chain operational procedures for signing transactions, including multiple approvers and incident response plans.

The EntryPoint is a singleton, trusted smart contract that orchestrates the validation and execution of UserOperations in ERC-4337. It is the system's central verification and bundling hub, ensuring only valid operations are included in a block. The Controller interacts with the EntryPoint to submit its signed UserOperations for processing.

• Core Function: Acts as the global verifier and executor for all account abstraction transactions.
• Trust Assumption: Users and wallets must trust the canonical EntryPoint contract address.
• Fee Handling: Manages the payment of gas fees, often using a paymaster.

A Smart Account (or Smart Contract Wallet) is a programmable Ethereum account, controlled by logic rather than a single private key. The Controller is the external owner or manager of this account.

• Key Difference: Unlike an Externally Owned Account (EOA), it is a contract with its own address and storage.
• Programmability: Enables features like multi-signature security, social recovery, gas sponsorship, and transaction batching.
• Controller Role: The Controller (e.g., a user's EOA or a multisig) holds the authority to initiate actions through the Smart Account via the EntryPoint.

A UserOperation is a pseudo-transaction object that represents a user's intent in ERC-4337. It is the fundamental data structure submitted by a Controller to the network.

• Structure: Contains fields for the sender (Smart Account), nonce, callData, signature, and paymaster data.
• Lifecycle: Created by the Controller, relayed by a Bundler, and processed by the EntryPoint.
• Abstraction: Decouples transaction signing and execution, allowing for flexible signature schemes and gas payment methods.

A Bundler is a network participant (often a node or a specialized service) that packages multiple UserOperations from Controllers into a single Ethereum transaction. It is essential for the economic viability of account abstraction.

• Primary Role: Acts as the transaction relayer and submitter to the blockchain.
• Gas Economics: Pays the base-layer gas fee for the bundled transaction and is reimbursed by the EntryPoint using fees from the UserOperations.
• Infrastructure: Similar to a block builder in today's mempool, creating a separate UserOperation mempool.

A Paymaster is a smart contract that can sponsor transaction fees on behalf of a user's Smart Account, enabling gasless transactions or payment in ERC-20 tokens. The Controller can specify a paymaster in their UserOperation.

• Sponsorship Model: Allows dApps or services to absorb gas costs for their users (meta-transactions).
• Validation: The Paymaster contract must pre-validate and agree to pay for the UserOperation.
• Flexible Payment: Can implement logic for subscription models, ad-sponsored tx, or token conversions.

A Signature Scheme defines the cryptographic method used by a Controller to authorize a UserOperation. Smart Accounts are not limited to the ECDSA scheme used by EOAs.

• Flexibility: Can utilize multi-sig (e.g., Gnosis Safe), threshold signatures, BLS signatures, or passkeys/WebAuthn.
• Validation Logic: The verification is performed by the Smart Account's validateUserOp function, allowing for custom rules.
• Security Models: Enables advanced recovery mechanisms and session keys for improved user experience without compromising security.