Module <-> library equivalence

[mudgen]

Abstract

I am building a general purpose smart contract library called Compose. @cameel suggested I use free functions instead of Solidity libraries for my particular use case. I think that is a great idea so I refactored Compose to use modules/free files and it works great but there are some small issues I'd appreciate being fixed or clarified.

I'm going to call files that do not generate their own bytecode and that are not meant to be deployed "modules" in this issue. They contain definitions of things that are defined outside any contract or Solidity library.

1. In a Solidity library I can access address(this) and in a free file/module I cannot. I would like to access address(this) in a module, or in free functions. Rationale: the whole purpose of the free functions I use is to import them and use them in contracts, so it makes sense to give them direct access to address(this), without dipping into assembly.

2. I cannot import a Solidity module and emit an event directly from it. Issue about that here: ICE when emitting an event via module member access #16314 Note that I can import a Solidity library and emit an event directly from it, but I am trying to replace Solidity libraries.

3. Improved NatSpec documentation for modules. I currently cannot write a NatSpec comment for a constant defined in a module. I can't write a NatSpec comment at the top of the module to document the module itself.

For example I would like to write the following NatSpec comment at the top of the module to document the module:

/**
* @title Diamond Module
* @notice Internal functions and storage for diamond proxy functionality.
* @dev Implements EIP-2535 Diamond Standard
* (https://eips.ethereum.org/EIPS/eip-2535)
*/

Motivation

Specification

Backwards Compatibility

[mudgen]

I think this issue should also be labeled as a bug.

[cameel]

I cannot import a Solidity module and emit an event directly from it.

This is now fixed: #16336. Will go into the next release.

I can't write a NatSpec comment at the top of the module to document the module itself.

The current plan is to eventually allow Natspec in many more places. We already have an issue for this: #12295. Let's move the discussion about modules and constants there.

Unfortunately, I'm not sure when we'll get around to this. We have limited capacity and most of the work goes into the big high-priority topics (SSA-CFG, ethdebug, Core Solidity). We do have a little headroom to squeeze in some smaller features like this, but there's a lot of them and they all compete with each other for development time.

In a Solidity library I can access address(this) and in a free file/module I cannot.

I initially assumed this must have been an oversight, but after digging into it I think it was likely intentional. When a library function depends on the contract, it technically becomes an implicit parameter. Making it explicit makes things clearer:

function withdrawAll(I i) {
    i.withdraw(address(i).balance);
}

interface I {
    function withdraw(uint amount) external;
}

contract C is I {
    function withdraw(uint amount) public {
        withdrawAll(this);
    }
}

The optimizer is even powerful enough to recognize that you're accessing this and replace BALANCE with the cheaper SELFBALANCE, as long as you're just directly passing it into the function.

This does couple your implementation to the contract, unfortunately, but as a workaround you can always pass in just the address. And if you want to make contract-agnostic external calls, an interface is what you want anyway. In Core Solidity it will be solved more elegantly, through generics, but I think what we have here is already workable. What do you think?

[cameel]

Other than this, did you find any other incompatibilities between free functions and libraries? I actually thought there would be more, but the only thing I could come up with is balance and external function calls. I saw someone complaining that free functions cannot have storage parameters, but that's not the case. I think they have access to all the stuff libraries can use: block/tx/msg properties, low-level calls, assembly, etc.

[mudgen]

@cameel That's great that emitting an event from an imported Solidity module is going into the next release. Really appreciate that, thank you.

Understood about NatSpec, hopefully the changes are not very hard so it gets a chance in an upcoming release.

I am not happy with the solution for address(this). I think you are right, it is intentionally not available, and I disagree with that. I expect all my free functions to be executed within a smart contract. I expect address(this) to always be part of my execution environment, same as other special variables such as msg.sender etc. I don't want to pass address(this) as an explicit argument -- that clutters my functions. Just like I don't want to pass msg.sender as an argument to a function.

Maybe address(this) isn't a good name, maybe it should be msg.contract or something. Maybe some people want to be explicit and pass address(this) as an argument to functions. That's fine, they can. But I suggest letting people use msg.contract or address(this) if they want to. That is better than dipping into assembly to do it.

[mudgen]

Other than this, did you find any other incompatibilities between free functions and libraries?

@cameel No I haven't. But if I run into more things I will let you know. I really appreciate you being there to receive and address these things. Thank you.

I really like this move to Solidity modules, thanks for pointing me in this direction.