interface-design

# Interface Design ## Interface Principles Interfaces define the external API of your protocol. They are the contract between your system and its integrators. ```solidity // Minimal, focused interface — one concern per interface interface IVault { function deposit(address token, uint256 amount) external returns (uint256 shares); function withdraw(address token, uint256 shares) external returns (uint256 amount); function balanceOf(address user, address token) external view returns (uint256); } // Separate admin interface interface IVaultAdmin { function setFee(uint256 feeBps) external; function pause() external; function unpause() external; } // Separate events interface — inheritable without implementation obligation interface IVaultEvents { event Deposited(address indexed user, address indexed token, uint256 amount, uint256 shares); event Withdrawn(address indexed user, address indexed token, uint256 amount, uint256 shares); } ``` ## Abstract Contracts vs Interfaces | Feature | Interface | Abstract Contract | |---------|-----------|-------------------| | State variables | No | Yes | | Constructor | No | Yes | | Function implementations | No | Partial | | Inheritance | Multiple | Multiple (with care) | | Use case | External API definition | Shared base logic | ```solidity // Abstract contract: provides base implementation with extension points abstract contract BaseVault is IVault, IVaultEvents, ReentrancyGuard { mapping(address => mapping(address => uint256)) internal _shares; function deposit(address token, uint256 amount) external virtual nonReentrant returns (uint256 shares) { shares = _convertToShares(token, amount); _shares[msg.sender][token] += shares; IERC20(token).safeTransferFrom(msg.sender, address(this), amount); emit Deposited(msg.sender, token, amount, shares); } // Extension point — subclasses define share calculation function _convertToShares(address token, uint256 amount) internal view virtual returns (uint256); } ``` ## Virtual / Override Use `virtual` to mark functions that can be overridden. Use `override` to implement them. Use both when a middle-layer contract overrides but allows further overriding. ```solidity abstract contract Pausable { bool public paused; modifier whenNotPaused() virtual { require(!paused, "Paused"); _; } function _pause() internal virtual { paused = true; } } contract Vault is Pausable { function deposit(uint256 amount) external whenNotPaused { // ... } // Override to add event emission function _pause() internal override { super._pause(); emit VaultPaused(block.timestamp); } } ``` ## EIP-165: supportsInterface Implement `supportsInterface` to allow onchain interface detection. ```solidity import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol"; contract MyToken is IERC165, IERC721 { function supportsInterface(bytes4 interfaceId) external pure override returns (bool) { return interfaceId == type(IERC165).interfaceId || // 0x01ffc9a7 interfaceId == type(IERC721).interfaceId || // 0x80ac58cd interfaceId == type(IERC721Metadata).interfaceId; // 0x5b5e139f } } ``` ### Computing Interface IDs ```solidity // Interface ID = XOR of all function selectors in the interface bytes4 constant IERC721_ID = bytes4( keccak256("balanceOf(address)") ^ keccak256("ownerOf(uint256)") ^ keccak256("safeTransferFrom(address,address,uint256,bytes)") ^ keccak256("safeTransferFrom(address,address,uint256)") ^ keccak256("transferFrom(address,address,uint256)") ^ keccak256("approve(address,uint256)") ^ keccak256("setApprovalForAll(address,bool)") ^ keccak256("getApproved(uint256)") ^ keccak256("isApprovedForAll(address,address)") ); // Or use Solidity's built-in: bytes4 id = type(IERC721).interfaceId; ``` ## Callback Interfaces Define callback interfaces for contracts that need to be notified of actions (flash loans, token receipts). ```solidity interface IFlashLoanReceiver { /// @notice Called by the lending pool after transferring the flash loan amount. /// @param token The address of the token borrowed. /// @param amount The amount borrowed. /// @param fee The fee to be paid on top of the borrowed amount. /// @param data Arbitrary data passed through from the flash loan initiator. /// @return Must return the keccak256 hash of "IFlashLoanReceiver.onFlashLoan" function onFlashLoan( address token, uint256 amount, uint256 fee, bytes calldata data ) external returns (bytes32); } // Verify callback return value bytes32 constant CALLBACK_SUCCESS = keccak256("IFlashLoanReceiver.onFlashLoan"); function flashLoan(address receiver, address token, uint256 amount, bytes calldata data) external { IERC20(token).safeTransfer(receiver, amount); bytes32 result = IFlashLoanReceiver(receiver).onFlashLoan(token, amount, fee, data); if (result != CALLBACK_SUCCESS) revert InvalidCallbackReturn(); IERC20(token).safeTransferFrom(receiver, address(this), amount + fee); } ``` ## Diamond Inheritance Solidity uses C3 linearization for multiple inheritance. Be explicit about resolution. ```solidity contract A { function foo() public virtual returns (string memory) { return "A"; } } contract B is A { function foo() public virtual override returns (string memory) { return "B"; } } contract C is A { function foo() public virtual override returns (string memory) { return "C"; } } // Must explicitly override — compiler enforces it contract D is B, C { function foo() public override(B, C) returns (string memory) { return super.foo(); // calls C.foo() (rightmost parent in linearization) } } ``` ## Interface Design Checklist - [ ] One concern per interface (separate user-facing from admin) - [ ] Events in their own interface for clean inheritance - [ ] EIP-165 `supportsInterface` implemented for discoverable contracts - [ ] Callback interfaces return a magic value for verification - [ ] `virtual` on functions intended for extension - [ ] NatSpec on all interface functions - [ ] Abstract contracts for shared base logic with extension points - [ ] Inheritance order consistent across the codebase - [ ] No diamond inheritance without explicit `override(A, B)` resolution