Skip to main content

Contract Metadata: Rich onchain identity for smart contracts

· 4 min read
Nischal Sharma
Nischal Sharma
Co-Founder and Lead Engineer at Enscribe

Contract metadata cover

Smart contracts are the backbone of onchain applications, but discovering information about them has always been fragmented. Contract metadata lives across multiple platforms — documentation on one site, audits on another like github, social links scattered everywhere. Basic information like "what does this contract actually do?" is often nowhere to be found.

Enscribe brings contract metadata onchain through ENS text records.

The contract metadata standard​

As part of the Contract Naming Season, we've been working on a draft ENSIP proposal for contract metadata standards. This proposal defines a set of text records that projects can use to attach information to their smart contracts.

When you look at a contract's ENS name, you can see who built it, what it does, where to find documentation, security audits, and more — all in one place.

Contract metadata fields​

Contract metadata display

Contract details pages show several categories of text records that contracts or their parent organizations can set:

Basic information​

  • name: Display name for the contract (e.g., "Uniswap V3 Router")
  • description: What the contract does
  • url: Official website or landing page
  • avatar: Contract logo or icon (IPFS hash, HTTP URL, or data URI)
  • header: Banner or background image

Social and community​

  • com.github: GitHub repository URL
  • com.twitter: Twitter/X profile
  • org.telegram: Telegram community link
  • com.linkedin: LinkedIn company page
  • Any other social text record you want to set

Documentation and audit reports​

  • docs: Documentation URL
  • audits: Security audit reports (can link to a page with multiple audits)
  • category: Contract type or category (e.g., "DeFi", "NFT", "Governance")
  • license: Software license information

Organization-level vs contract-level metadata​

Metadata inheritance lets you set metadata at the organization level (the parent ENS name) and have it automatically apply to all contracts under that name.

For example, if you set an avatar and social links on protocol.eth, all contracts named under it (router.protocol.eth, factory.protocol.eth, etc.) will inherit those values — unless they set their own.

protocol.eth (organization)
├─ avatar: ipfs://QmXyz...
├─ com.github: github.com/protocol
├─ com.twitter: twitter.com/protocol
│
├─ router.protocol.eth
│  └─ inherits all metadata from protocol.eth
│
├─ factory.protocol.eth
   ├─ description: "Factory contract for creating pairs"
   └─ inherits avatar and social links from protocol.eth

This means you can establish your project's identity once at the top level, and all your contracts benefit from it. You only need to set contract-specific details (like descriptions or audit links) for individual contracts.

The contract explore page​

The contract explore page displays this metadata.

New contract page layout

Header and avatar section

  • Circular avatar prominently displayed
  • Header image as a subtle background
  • Contract name and description
  • Social links with branded icons, making it easy to find official channels

Clean layout

  • Contract details like docs, audits, category, license organized in clear sections
  • ENS management and organization information (owner, manager, parent)
  • Contract deployer and verification status
  • ABI and source code when verified on Sourcify

All text records are visible in a dedicated metadata section.

Why this matters​

Set contract information once, inherit everywhere. Projects establish a single source of truth through ENS name ownership. Set branding and metadata at the organization level, then all contracts inherit it automatically.

Users verify before signing. Check official links, documentation, and audit reports directly from contract metadata. See who's behind a contract and what it does at a glance.

Onchain, not centralized. Contract metadata lives onchain through ENS text records. No reliance on external databases or APIs that can go offline.

Standard format across all projects. Any tool can read and display contract metadata. The system is extensible — projects can add custom fields beyond the standard set.

For technical details on how metadata is retrieved and the public API, see the contract metadata docs page.

Join the conversation​

We'd love to hear your thoughts on contract metadata:

  • What fields would be most useful for your projects?
  • What other information should be standardized?
  • How are you using contract metadata?

Share your feedback on Discord, Telegram, or X. Or start a discussion on GitHub.

Contract metadata brings order to onchain information. With a standard approach to contract identity, we can build better tools, clearer interfaces, and more transparent onchain interactions.

Happy naming! 🚀