Skip to main content

Source Path Translation

In the folder of a contract you will sometimes find a file called path-translation.json. This file contains the path translations of source files from how it's stated in the original metadata to how it is actually saved in the repository.

The files look like this (formatted here for readability):

{
  "https://github.com/repo/blob/master/contracts/token/ERC20/../../Context.sol": "https:/github.com/repo/blob/master/contracts/Context.sol"
}

This is needed because the source file paths in the metadata are in fact not paths but "source unit names" (as explained here). They are found under .sources:

  // metadata.json
  ...
  "sources": {
    "contracts/1_Storage.sol": { // source unit name
      "keccak256": "0xb6ee9d528b336942dd70d3b41e2811be10a473776352009fd73f85604f5ed206",
      "license": "GPL-3.0",
      "urls": [
        "bzz-raw://fe52c6e3c04ba5d83ede6cc1a43c45fa43caa435b207f64707afb17d3af1bcf1",
        "dweb:/ipfs/QmawU3NM1WNWkBauRudYCiFvuFE1tTLHB98akyBvb9UWwA"
      ]
    }
  },

Even though usually they look like paths, they can be arbitrary strings. Because Sourcify currently does not work with a database and is a file system, we have to sanitize these source unit names to be valid file paths. This includes removing any potentially dangerous path traversals, normalizing path separators (e.g. // to /), and making absolute paths relative.

We don't do any translation on the characters. This has some downsides:

  1. Some of the path names will not be Windows compatible. Unix formats almost any character in a path name, but Windows has some restrictions.
  2. Some file names won't be directly accessible via the static serving endpoint. E.g. a file called contract#1.sol won't be available at /repository/contracts/full_match/0xab..cd/sources/contract#1.sol because the # is a special character in URLs.

To access contract files, instead use /files/{chain}/{address} or /files/any/{chain}/{address} as laid out in the API documentation that return all files in a JSON array.

When you need to process files locally and need to handle the differences between the metadata file and the actual file system, you can use the path-translation.json file to translate the paths.