solc-metadata

This is the minimum JavaScript required to fetch, extract, decode, and use the metadata (or "auxdata") that the Solidity compiler (solc) appends to the end of a smart contract's runtime bytecode.

Similar to sourcify's metadata playground (website, GitHub) but reduced to the bare minimum code.

Code repository mirrors: GitHub, Codeberg, git.ardis.lu

Fetch

By default, the Solidity compiler appends metadata to the end of a smart contract's runtime bytecode. A smart contract's runtime bytecode may be fetched from any Ethereum node using the standard JSON-RPC method eth_getCode.

The runtime bytecode is different from the creation bytecode. The creation bytecode is the code that's used to create the smart contract. The creation bytecode includes extra operations required to deploy the runtime bytecode (i.e. the constructor logic and arguments). Consequently, the runtime bytecode will look different from the creation bytecode.

Extract

After the runtime bytecode is fetched, the metadata (or "auxdata") may be extracted by reading the last ~53 or so bytes from the end of the runtime bytecode. The exact length will vary depending on the version of solc and the exact compiler settings used to compile the bytecode. See the solc docs for details about how this metadata is encoded and how exactly to extract the metadata.

Decode

The metadata in the runtime bytecode is CBOR (Concise Binary Object Representation) encoded. A minimal and limited CBOR decoder is implemented to convert the CBOR into JSON.

Use

Here are the possible keys that solc may encode into the bytecode (as of v0.8.24):

The table above was created by researching the solc changelog and archived versions of the official solc documentation. Check the changelog and the documentation for the latest details.

The ipfs value in the decoded metadata is not a CID. It's a multihash of the sha256 hash of the full JSON metadata file. The multihash must be converted into a CID to be usable. Minimal transformation functions are implemented to convert the multihash into both CIDv0 and CIDv1.

Once the CID is calculated, you may finally use the CID to retrieve the full JSON metadata from IPFS (assuming someone has pinned the JSON file in IPFS).

If the smart contract was compiled using an old version of solc (before v0.6.0), then the metadata may only contain bzzr0 or bzzr1 keys. In this case, the tool is unable to fetch the metadata because there are no easily accessible public Swarm gateways, and it's unlikely the metadata is still hosted anyway.

TypeScript

index.d.ts is generated from the JSDoc comments in index.js using tsc:

tsc --declaration --emitDeclarationOnly --allowJs ./index.js