Metadata v2
- Dominant language
- C++
- Stars
- 25.7k
- Forks
- 6.2k
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 21
Description
## Abstract
Introduce a new version of the [JSON metadata](https://docs.soliditylang.org/en/develop/metadata.html#contract-metadata), with a corrected `settings` object that matches the one in Standard JSON input.
## Motivation
As listed in https://github.com/ethereum/sourcify/issues/1523, there are two structural differences between Standard JSON's `settings` object and the one in JSON metadata:
1. The format of `libraries` in Standard JSON and in metadata is not the same:
- metadata: `{"L.sol:L": "0x7d53f102f4d4aa014db4e10d6deec2009b3cda6b"}`
- settings: `{"L.sol": {"L": "0x7d53f102f4d4aa014db4e10d6deec2009b3cda6b"}}`
- Note that this variant does not support unqualified library names (see #12145), but the plan is to disallow them anyway.
1. The `settings.compilationTarget` field in metadata logically does not belong to settings. It corresponds to the `sources` field in Standard JSON and therefore would make more sense at the top level.
These differences are a minor inconvenience for tools. The `settings` cannot be used as-is and have to be adjusted when trying to recompile the project based on metadata. There's no good reason for these differences to exist in the first place.
Since the changes to the structure are not backwards-compatible, we have to bump the metadata version to introduce them.
### Specification
1. Introduce `--metadata-version`/`settings.metadata.version` setting that accepts an integer version. It should allow selecting between `1` and `2` and result in the chosen version being set in the `version` field in JSON metadata. The default is `1`.
1. Apply the structural changes listed above to metadata v2.
- Report an error if metadata v2 is selected and an unqualified library name is present in `--libraries`.
1. Issue a deprecation warning when metadata v1 is requested.
1. Document the new format.
## Backwards Compatibility
The change is fully backwards compatible, because we keep the current behavior by default and the new one has to be explicitly opted into via `--metadata-version 2`. We will not change the default until the next breaking version.
Contributor guide
Research direction
Start by tracing the compiler entry points for --metadata-version, settings.metadata.version, --libraries, and JSON metadata generation. Compare the existing metadata structure with Standard JSON input and the linked metadata documentation; done means selectable versions 1 and 2, the specified v2 structure and validation, the v1 warning, and documented behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, solidity
- Domain
- compilers, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100