Sourcify: full verification for Solidity and Vyper contracts

Verification by metadata hash rather than by bytecode match

Sourcify is a source code verification service for Ethereum smart contracts supporting Solidity and Vyper, and its distinguishing mechanism is how it decides that a contract matches its source.

The README says it differs from other verification services because Sourcify leverages the Solidity metadata and its integrity hash to fully verify Solidity contracts. That is a stronger claim than a bytecode comparison, and the difference matters.

A compiler embeds a metadata blob into the deployed bytecode, and that blob contains the compiler settings and a hash of the source files. Sourcify extracts that CBOR encoded metadata from the bytecode, parses it, and checks the hash against the sources you supply. If the hashes line up, the source you published is provably the source that produced that bytecode, up to the strength of the hash. A partial match, by contrast, only tells you that some metadata was found and some fields agreed, which is what a looser service typically offers.

That mechanism is why the project is committed to open standards through the Verifier Alliance, rather than running its own private notion of verification. If the verification result is to mean anything outside Sourcify, the method has to be one anyone can implement, and the same reasoning explains the open data commitment, since the verified contracts and their metadata are meant to be downloadable rather than locked inside a service.

The audience is contract authors, auditors and infrastructure teams who want a verification result that a third party can reproduce.

Three services, four packages and two separate web interfaces

The repository is a monorepo, and the README breaks it into services and packages.

sourcify-server is the HTTP server that runs source code verifications and stores the verified contracts for the supported chains through an API. sourcify-database is a PostgreSQL database that stores the verified contracts and their metadata, and it is also the repository for the database schema and migrations. sourcify-monitor is the piece that makes verification happen without anyone asking, a standalone service that listens to various EVM chains for new contract creations and automatically submits them to a Sourcify API for verification if published on IPFS.

The packages carry the shared logic. @ethereum-sourcify/lib-sourcify is the core library containing the logic to verify contracts. @ethereum-sourcify/bytecode-utils extracts and parses the CBOR encoded metadata from the bytecode, which is the first step of a full verification. @ethereum-sourcify/compilers is a wrapper around the Solidity and Vyper compilers that downloads the right version and invokes the compilation through a common interface, so the caller does not have to know which compiler produces which artefact. @ethereum-sourcify/compilers-types holds the TypeScript types for the compilers.

The two web interfaces live in other repositories rather than here. The Sourcify UI interacts with the server, looks up and verifies contracts, and repo.sourcify.dev browses and displays verified contract information. The README notes that this monorepo contains the main modules and that the sourcifyeth GitHub organisation holds all the auxiliary services and components.

The split has a practical consequence. If you are self hosting, you are running the server, the database and the monitor, and you may or may not want the browser interfaces, which are separate deployments.

The monitor turns IPFS publication into automatic verification

The monitor service is the most interesting piece architecturally, because it changes who does the work.

Normally, verification happens when a developer submits a contract after deploying it. The monitor reverses that. It listens to various EVM chains for new contract creations, and when it sees one, it checks whether the contract was published on IPFS and, if so, automatically submits it to a Sourcify API for verification.

That closes a loop that has three separate technologies in it. The contract deployment is observed on chain, the source travels through IPFS, and the verification runs against a Sourcify API. The result is that a developer who publishes sources to IPFS at deploy time gets verified contracts without submitting anything by hand.

The dependency on IPFS is also the constraint. A contract whose sources are not on IPFS is invisible to the monitor, so the automation only covers the deployment habits of teams that already publish to IPFS. Everything else still goes through the API by hand.

The README also mentions that the infrastructure is powered by dRPC. That is a hosted service dependency worth noting before you rely on the service in production.

Running the monorepo locally with lerna and npm workspaces

The root package.json describes itself as the Sourcify monorepo containing all Sourcify packages and services, with npm workspaces over packages/* and services/*, and lerna driving the per package tasks. The workspace declaration is what makes a single install cover every service:

  "workspaces": [
    "packages/*",
    "services/*"
  ],

Each service has a start script, and the three that matter for a local run are:

    "server:start": "cd services/server && node ./dist/server/cli.js",
    "monitor:start": "node ./services/monitor/dist/index.js",
    "4byte:start": "node ./services/4byte/dist/cli.js",

The start scripts expect compiled output, so a build comes first. The lerna scripts cover that and the quality checks:

    "build:lerna": "lerna run build",
    "lerna-test": "lerna run test --stream",
    "lerna-lint": "lerna run check",
    "lerna-version": "lerna version --no-push",

There is one more script worth knowing about. The build:clean script prints a warning that it is executed without the Socket DEV cli and asks you to run npm install afterwards to check for vulnerabilities, then removes the node_modules of every service and package, reinstalls, and runs the lerna build. That warning is a reminder that this project treats dependency scanning as part of the build cycle rather than as an optional extra.

The rest of the tooling is visible in the repository root: an .nvmrc pinning the Node version, nx.json and lerna.json for task orchestration, husky for git hooks via the prepare script, renovate.json for dependency updates, eslint.config.js, .prettierrc and codecov.yml for linting, formatting and coverage.

Open data, open standards and a public roadmap

The project states three commitments and then says it fosters these values across the ecosystem. Open-source under the MIT licence, open-data with the verified repository documented for downloading, and open-standards through the Verifier Alliance, in place of siloed proprietary services.

That positioning explains a lot of the engineering choices. The chain support instructions live in the public documentation rather than in an internal runbook, so adding a chain is a documented procedure rather than a request to the maintainers. The public issue board and the quarterly milestones boards are linked from the README, which means the day to day work and the longer term plans are visible.

The documentation itself is a separate concern, hosted at docs.sourcify.dev, with pages for the metadata format, the API, the difference between full and partial match, and the chain support procedure. There is a playground linked from the README for trying a verification without deploying anything, which is the fastest way to understand what the service actually checks.

For governance, Sourcify is an Argot Collective project, and the repository carries FUNDING.json. The Verifier Alliance is worth understanding if you are building tooling around contract verification, because the point of a standards body here is that a competing service could verify the same way and reach the same conclusion.

MIT licence, a staging branch and versioned services

The licence is MIT, and the README lists open-source under the MIT licence as the first of the three commitments. For a verification service whose purpose is public reproducibility, a permissive licence on the server, the database and the libraries is the only consistent choice, and it means an organisation can run its own instance and modify it without a copyleft obligation.

The default branch is staging, not main or master. That is a meaningful detail for contributors and for anyone integrating with the deployment, since the branch layout tells you that the default line is where work lands before it is cut into releases.

Releases are per service rather than for the repository as a whole, which reflects the monorepo structure. The recent tags are sourcify-server at 4.1.2, sourcify-monitor at 1.6.4 and sourcify-database at 2.15.2, all published on 2026-10-05. Three services with three independent version lines means you can upgrade the monitor without touching the server, and it also means you have to track three sets of changes rather than one.

The last push was on 2026-10-19, and the working method is documented in the README: the public issue board for day to day work and the quarterly milestones board for longer term plans, plus a CLAUDE.md at the repository root alongside a .circleci directory, .husky hooks and GitHub workflows.

One limitation is worth stating plainly. The README does not document which chains are currently supported, so a team planning to verify contracts on a specific network should check the chain support documentation before committing to the service, and the same applies to compiler versions, where the compilers package fetches the version you ask for but the supported range is not spelled out in the README itself.

Editorial conclusion

Sourcify fits contract authors who want their deployed source to be checkable by anyone, and infrastructure teams who want a verification backend they can run themselves rather than a proprietary API. It does not fit projects that only need a quick bytecode match on a single chain. Verify first that your compiler version and chain are covered, that the metadata in your deployed bytecode still carries the integrity hash, and that your build pipeline can emit the metadata files the verification API expects, since the full match depends on them.

Frequently asked questions

Official sources

1. argotorg/sourcify on GitHub
2. License: MIT
3. Project website
4. README
5. Releases