@synthetixio/hardhat-router

hardhat-router

Solidity router generator.

Description

This hardhat plugin generates a router contract which simply merges multiple contracts (modules) behind a single proxy.

The router proxy receives incoming calls and forwards them to the appropriate implementation or module, depending on which one contains the incoming function selector.

Example: A user calls the rebalancePool() function on a deployed router, which merges 3 modules; A.sol, B.sol, and C.sol. The router determines that the function rebalancePool is defined in module B.sol. So, the router simply performs a DELEGATECALL to B's deployed instance.

This router is similar to the Diamond Proxy but:

• is simpler
  • because it has no module management interface
• more explicit
  • because its modular composition can easily be seen by looking at its hardcoded module addresses
• more efficient
  • because it hardcodes the deployed module addresses, minimizing SLOAD usage

Module deployment

The plugin will consider any contract inside a modules folder (configurable) a module, and automatically detect if its bytecode has changed and deploy it.

Router generation

After module deployment, the router's source code is generated by the plugin. Generation will fail under certain conditions, e.g. if two of the modules contain the same selector, or a function with the same name.

Example output:

contract Router {
    error UnknownSelector(bytes4 sel);

    address private constant _OWNER_MODULE = 0x5FbDB2315678afecb367f032d93F642f64180aa3;
    address private constant _SNXTOKEN_MODULE = 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512;
    address private constant _SYNTHS_MODULE = 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0;
    address private constant _UPGRADE_MODULE = 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9;

    fallback() external payable {
        _forward();
    }

    receive() external payable {
        _forward();
    }

    function _forward() internal {
        // Lookup table: Function selector => implementation contract
        bytes4 sig4 = msg.sig;
        address implementation;

        assembly {
            let sig32 := shr(224, sig4)

            function findImplementation(sig) -> result {
                if lt(sig,0x81d49b75) {
                    if lt(sig,0x53a47bb7) {
                        switch sig
                        case 0x0f36a2de { result := _SYNTHS_MODULE } // SynthsModule.createSynth()
                        case 0x1627540c { result := _OWNER_MODULE } // OwnerModule.nominateNewOwner()
                        case 0x2d6b3a6b { result := _SYNTHS_MODULE } // SynthsModule.getBeacon()
                        case 0x35eb2824 { result := _OWNER_MODULE } // OwnerModule.isOwnerModuleInitialized()
                        case 0x3659cfe6 { result := _UPGRADE_MODULE } // UpgradeModule.upgradeTo()
                        case 0x51456061 { result := _SYNTHS_MODULE } // SynthsModule.getSynth()
                        leave
                    }
                    switch sig
                    case 0x53a47bb7 { result := _OWNER_MODULE } // OwnerModule.nominatedOwner()
                    case 0x57d7995a { result := _SYNTHS_MODULE } // SynthsModule.createSynthImplementation()
                    case 0x624bd96d { result := _OWNER_MODULE } // OwnerModule.initializeOwnerModule()
                    case 0x7104fba5 { result := _SYNTHS_MODULE } // SynthsModule.getSynthImplementation()
                    case 0x718fe928 { result := _OWNER_MODULE } // OwnerModule.renounceNomination()
                    case 0x79ba5097 { result := _OWNER_MODULE } // OwnerModule.acceptOwnership()
                    leave
                }
                if lt(sig,0xd1b6c504) {
                    switch sig
                    case 0x81d49b75 { result := _SNXTOKEN_MODULE } // SNXTokenModule.getSNXTokenModuleSatellites()
                    case 0x8da5cb5b { result := _OWNER_MODULE } // OwnerModule.owner()
                    case 0xa44896e7 { result := _SYNTHS_MODULE } // SynthsModule.isSynthsModuleInitialized()
                    case 0xaaf10f42 { result := _UPGRADE_MODULE } // UpgradeModule.getImplementation()
                    case 0xc6253216 { result := _SYNTHS_MODULE } // SynthsModule.upgradeSynthImplementation()
                    case 0xc7f62cda { result := _UPGRADE_MODULE } // UpgradeModule.simulateUpgradeTo()
                    leave
                }
                switch sig
                case 0xd1b6c504 { result := _SNXTOKEN_MODULE } // SNXTokenModule.getSNXTokenAddress()
                case 0xdaac1198 { result := _SNXTOKEN_MODULE } // SNXTokenModule.upgradeSNXImplementation()
                case 0xe040da24 { result := _SNXTOKEN_MODULE } // SNXTokenModule.isSNXTokenModuleInitialized()
                case 0xf4c4dc31 { result := _SYNTHS_MODULE } // SynthsModule.getSynthsModuleSatellites()
                case 0xf5d6f068 { result := _SNXTOKEN_MODULE } // SNXTokenModule.initializeSNXTokenModule()
                case 0xfbc6aa6f { result := _SYNTHS_MODULE } // SynthsModule.initializeSynthsModule()
                leave
            }

            implementation := findImplementation(sig32)
        }

        if (implementation == address(0)) {
            revert UnknownSelector(sig4);
        }

        // Delegatecall to the implementation contract
        assembly {
            calldatacopy(0, 0, calldatasize())

            let result := delegatecall(gas(), implementation, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())

            switch result
            case 0 {
                revert(0, returndatasize())
            }
            default {
                return(0, returndatasize())
            }
        }
    }
}

Router validation

After generation, the plugin performs a series of validations on the generated source, including:

• Checks that there are no duplicate selectors in its modules (function names must be unique)
• That there are no storage collisions between module namespaces
• That there are no invalid storage mutations between module namespaces
• TODO: Complete list of validations

Storage namespaces

To avoid storage collisions between modules, we recommend the usage of storage namespaces.

Instead of declaring variables in regular Solidity slots:

contract SettingsModule {
	uint private _someSetting;

  function setSomeSetting(uint newValue) external {
    _someSetting = newValue;
  }

  function getSomeSetting() external view returns (uint) {
    return _someSetting;
  }
}

Use a store:

contract SettingsModule is SettingsStorage {
	function setSomeSetting(uint newValue) external {
    _settingsStore().someSetting = newValue;
  }

  function getSomeSetting() external view returns (uint) {
    return _settingsStore().someSetting;
  }
}

contract SettingsStorage {
  struct SettingsStore {
    uint someSetting;
  }

  function _settingsStore() internal pure returns (ProxyStore storage store) {
    assembly {
      // bytes32(uint(keccak256("io.synthetix.settings")) - 1)
      store.slot = 0x312...
    }
  }
}

Inter-modular communication and mixins

Since the router DELEGATECALLs to its implementation modules, all code specified by its modules will be run within a single execution context. If the router is used directly, it will be the execution context. If something is DELEGATECALLing the router, then that will be the execution context. E.g. a proxy.

Thus, all modules have access to the global storage of the system. Instead of performing calls to other modules, it is recommended to use Mixins that know how to interact with the storage of another module.

E.g.

contract OwnableMixin is OwnableStorage {
  modifier onlyOwner() {
    require(msg.sender == _ownerStore().owner, "Only owner allowed");
    _;
  }
}

contract SynthsModule is SynthsStorage, OwnableMixin {
  function createSynth(...) external onlyOwner {
    ...
  }
}

No constructors

Since the router DELEGATECALLs to its modules, they storage will never be used. Any storage that may have been set by a constructor during module deployment will be ignored. Thus, we recommend to avoid using constructors in modules, and use initializer functions instead.

Upgradeability

If the router is used as the implementation of a UUPS Universal Upgradeable Proxy Standard proxy, and includes an UpgradeModule, it can be used to design complex systems which are upgradeable until the main proxy is upgraded to a router implementation that no longer has an UpgradeModule.

This plugin will deploy a proxy and set its implementation as the router.

Plugin configuration

hardhat.config.js

module.exports = {
  solidity: '0.8.11'
  networks: {
    ...
  },
  router: {
    paths: {
      deployments: 'deployments', // path to store deployment artifacts
      modules: 'modules',         // path where to find module contracts
    },
  },
};