Smart Contract Verification

A deployed smart contract is a blob of EVM bytecode at an address. Nothing in that bytecode tells a user who wrote it, which source it was compiled from, or whether it has been audited. Block explorers partially solve this with source uploads, but that solution is centralized, per-chain, and impersonatable. Notareum binds a contract address to an issuer identity, a source commit, and (optionally) an audit attestation, then anchors the binding in the on-chain NotaRegistry with validator signatures.

What a contract `.nota` proves

A .nota file for a deployed contract carries:

The chainId and identifier (the contract address).
The issuer identity (developer, DAO, or protocol team) that signed the file.
A pointer to the verified source bundle (git commit hash, IPFS CID, or explorer URL).
Optional audit metadata: auditor name, report hash, severity summary, audit date.
A verification level set by validator quorum after independent review.

The combination of a valid signature, a non-revoked registry entry, and a VERIFIED or higher level gives a wallet or dapp a single on-chain question to answer: is this contract what its deployer says it is?

Trust model

The deployer does not need the wallet to trust them: they need the wallet to trust the signature and the validator quorum. Because the deployer’s address already deployed the contract, a signature from the same key over the .nota file closes the loop cryptographically.

Creating the contract `.nota`

import { Notareum } from "@notareum/sdk";
import { Wallet } from "ethers";

const deployer = new Wallet(process.env.DEPLOYER_PK!, provider);
const ntm = Notareum({ provider, signer: deployer, contracts });

const nota = await ntm.nota
  .create({
    type: "contract",
    chainId: 1,
    chainName: "ethereum",
    identifier: "0xC0ffee254729296a45a3885639AC7E10F9d54979",
    name: "Acme Vault v2",
    description: "Audited ERC-4626 vault. Upgradeable via 7-day timelock.",
    alias: "acme-vault-v2.eth",
    resourceMetadata: {
      sourceCommit: "9a7f2c1e4b0d5e8fa3b2c7d1e0f6a9b4c8d2e5f7",
      sourceRepo: "github.com/acme/contracts",
      sourceIpfs: "bafybeigdyrzt6f...",
      compiler: "solc-0.8.24+commit.e11b9ed9",
      optimizer: { enabled: true, runs: 200 },
      audits: [
        {
          auditor: "Trail of Bits",
          reportHash: "0x7a9c2f8e...",
          date: "2026-03-12",
          findings: { critical: 0, high: 0, medium: 2, low: 5 },
        },
      ],
      upgradeable: true,
      proxyType: "UUPS",
      timelockSeconds: 604800,
    },
    issuerName: "Acme DAO",
    issuerEntityType: "organization",
  })
  .validate()
  .sign(deployer);

await ntm.registry.registerResource(nota);
await ntm.verification.requestVerification(nota.resourceId(), { level: "institutional" });

The identifier MUST equal the deployed contract address. Validators fetch the deployed bytecode, compile the referenced source with the declared compiler settings, and reject the attestation if the resulting runtime bytecode does not match.

Consumer verification

A wallet or dapp verifying a contract before interaction runs four checks:

import { Notareum, VerificationLevel } from "@notareum/sdk";

const ntm = Notareum({ provider, contracts });

async function assertContractTrusted(
  nota: string,
  required: VerificationLevel = "enhanced"
) {
  const parsed = ntm.nota.parse(nota);
  ntm.nota.validate(parsed); // 1. schema + signature

  const id = ntm.nota.resourceId(parsed);
  const record = await ntm.registry.getResource(id); // 2. on-chain lookup
  if (record.isRevoked) throw new Error("Contract revoked by issuer");

  if (VerificationLevel.rank(record.level) < VerificationLevel.rank(required)) {
    throw new Error(`Level ${record.level} below required ${required}`);
  } // 3. verification level

  const onChainCode = await provider.getCode(parsed.resource.identifier);
  if (onChainCode === "0x") throw new Error("No code at address");
  // 4. bytecode sanity: deployed code exists

  return {
    name: parsed.resource.name,
    issuer: parsed.issuer.name,
    level: record.level,
    sourceCommit: parsed.resource.resourceMetadata.sourceCommit,
    audits: parsed.resource.resourceMetadata.audits,
  };
}

A dapp can display “Interacting with Acme Vault v2 (verified by Acme DAO, audited by Trail of Bits)” on its confirm screen, with a single click-through to the source commit and audit report.

Proxy and upgradeable contracts

Upgradeable contracts complicate verification because the logic contract behind the proxy can change. Notareum handles this in two ways:

Proxy-level .nota targets the proxy address and declares upgradeable: true. The verification level applies to the proxy and its upgrade process (timelock, admin, governance controls), not to the current implementation.
Implementation-level .nota targets the current logic contract address. Each upgrade publishes a new implementation .nota referencing the new commit. A wallet can enforce both: “proxy must be verified AND the current implementation must be verified”.

async function checkProxyAndImpl(proxyAddr: string) {
  const proxyRecord = await ntm.registry.getResourceByAddress(1, proxyAddr);
  const implAddr = await proxy.implementation();
  const implRecord = await ntm.registry.getResourceByAddress(1, implAddr);
  return { proxyRecord, implRecord };
}

Audit attestations

Audit firms can operate as validators. An audit firm’s validator node submits a dedicated attestation with a structured payload:

{
  "auditor": "Trail of Bits",
  "reportUri": "ipfs://bafybeigdyrzt...",
  "reportHash": "0x7a9c2f8e...",
  "findings": { "critical": 0, "high": 0, "medium": 2, "low": 5 },
  "scope": { "commit": "9a7f2c1e...", "files": ["src/Vault.sol"] },
  "signedAt": 1713456000
}

The auditor’s signature on this payload is an on-chain, machine-readable audit badge. Wallets can surface this directly: “Audited by Trail of Bits (0 critical, 0 high)”.

Revocation and recompiles

Revocation fits naturally here:

A contract discovered to have a vulnerability gets its .nota revoked by the issuer. Consumers treating a revoked entry as untrusted immediately stop routing users to it.
A deployer who loses control of the deployer key revokes the associated .nota, then registers a new one from a replacement key controlled by the DAO.
A proxy upgrade to a malicious implementation triggers auto-revocation by a watcher validator if the new impl’s .nota is missing.

Integration patterns

Block explorers fetch .nota records alongside bytecode and render a “Notareum Verified” badge.
Wallets require at least ENHANCED verification before enabling approval-heavy actions (permit, approve(max), upgradeable proxy interactions).
DEX aggregators filter pool routes through registered contracts to avoid honeypots.
Security products subscribe to ResourceRevoked events to surface warnings within minutes of an incident.

Getting Started

Protocol

Token

SDKs

Guides

Use Cases

Smart Contracts

Reference

Resources

Smart contract verification

Smart Contract Verification

What a contract `.nota` proves

Trust model

Creating the contract `.nota`

Consumer verification

Proxy and upgradeable contracts

Audit attestations

Revocation and recompiles

Integration patterns

​Smart Contract Verification

​What a contract .nota proves

​Trust model

​Creating the contract .nota

​Consumer verification

​Proxy and upgradeable contracts

​Audit attestations

​Revocation and recompiles

​Integration patterns

​Related pages

Smart Contract Verification

What a contract `.nota` proves

Trust model

Creating the contract `.nota`

Consumer verification

Proxy and upgradeable contracts

Audit attestations

Revocation and recompiles

Integration patterns

Related pages