Semantic Dapp

Paste a contract address. Get a usable app.

Semantic Dapp turns any deployed EVM contract into a clean user dApp, an admin console, and a raw developer interface - no hand-written React forms, calldata encoding, role checks, or transaction-state juggling.

_{Mainnet USDC demo — same User · Admin · Read · Raw tabs for any contract. On the live page, use Load your contract for your own address/ABI. Try it live →}

_{Deterministic-first · AI-assisted, never AI-trusted · Self-hostable · Open source}

🚀 Live demo - USDC demo + Load your contract (address or ABI) in the browser · 📖 How it works (writeup) · 📓 Changelog · 🗺️ Roadmap

⭐ If this could save you from writing one more bespoke admin panel, star the repo - it genuinely helps.

---

The problem

Every team that ships a contract ends up rebuilding the same throwaway UI: a wallet button, a form per function, calldata encoding, hasRole checks, gas estimation, a spinner, an error decoder, and a "danger zone" for the scary admin methods. It's tedious, easy to get wrong, and it rots the moment the ABI changes.

Etherscan's Write Contract tab gives you raw inputs with zero meaning. Bespoke frontends give you meaning but cost weeks. Semantic Dapp gives you both - a UI that understands the contract, generated from the ABI (and source/NatSpec when available), that you can review, trust, and self-host.

What you get

🧩 Import anything By chain + address (Sourcify / block explorer, proxy-aware) or by pasting an ABI / Foundry artifact.

🔎 Understand it Deterministic detection of standards, roles, permissions and risk - with a confidence score and evidence, not a black box.

🖥️ Use it Auto-generated User, Admin and Raw tabs. Connect a wallet, simulate, and execute reads/writes safely.

Features

• 🧠 Semantic manifest - a reviewable, machine-readable understanding of the contract that sits between analysis and UI. Edit it, export it, version it.
• 🏷️ Standards & access detection - ERC-20 / 2612 / DAI-permit / 777 / 721 / 1155 / 4626, rebasing & fee-on-transfer advisories, OZ Governor + Bravo/Alpha, Ownable / AccessControl / Pausable / upgradeable (incl. diamondCut), via a member-based rule engine.
• 📜 NatSpec & source access hints - descriptions, param labels, and privilege upgrades from modifiers / body-level checks when verified source is available; PermissionBadge shows why a function is admin.
• 🪞 Proxy & diamond aware - EIP-1967 / 1167 / Safe / ERC-897 / Delegator / EIP-2535 facets; unresolved-shell warnings + manual implementation override.
• 🛡️ Safety first - role-by-name pickers with live hasRole badges, "type CONFIRM" gates on critical actions, homoglyph/bidi text sanitization, staleness detection when a proxy is upgraded.
• ✍️ Real execution - viem + wagmi reads, calldata Preview + eth_call dry-run before signing, gas estimation, decoded revert reasons, and a local audit trail.
• 📦 Export a standalone dApp - package identity + ABI + reviewed manifest into a portable bundle and host it anywhere. No Semantic Dapp cloud, ever.
• 🧰 CLI - build, export, and serve apps headlessly (semantic-dapp bundle | export | serve).
• 🔌 Wallet-fallback reads - if a public RPC is missing or rate-limited, reads fall back to the connected wallet's provider.
• ♿ Accessible & tested - axe-core a11y gate, unit + e2e tests, real-contract corpus harness, and analyzer tests driven by compiled Foundry ABIs.

How it works

flowchart LR
    A[Address or ABI] --> B[Resolver<br/>Sourcify · explorer · proxies]
    B --> C[Analyzer<br/>standards · access · risk]
    C --> D[Classifier<br/>operation type · audience]
    D --> E[Semantic Manifest<br/>reviewable · versioned]
    E --> F[Renderer<br/>User · Admin · Raw]
    F --> G[Execution<br/>preview · simulate · sign]
    E -.export.-> H[Standalone dApp<br/>+ CLI]

Loading

Everything upstream of the UI is deterministic-first: known patterns are recognized by rules with explicit evidence and confidence. AI may propose a label, but it never signs a transaction and never hides uncertainty — anything unproven falls back to the Raw tab, where writes are fail-closed (Preview + execution envelope + confirm + typed CONFIRM; stricter than classified high-risk).

Quick start

Requirements: Node >=20, pnpm >=10, and Foundry (only for the contract fixtures).

git clone https://github.com/TacitvsXI/semantic-dapp.git
cd semantic-dapp
pnpm install
pnpm build

# Launch the Studio (import → review → preview → export)
pnpm --filter @semantic-dapp/studio dev

Then open the Studio, paste a contract address (or an ABI), and preview the generated app. Prefer to see it instantly? Render one of the ready-made demos:

pnpm gen:demos                                  # build demo bundles from the fixtures
pnpm --filter @semantic-dapp/generated-app dev  # render a bundled dApp

Use as a library (npm)

All the building blocks are published to npm under the @semantic-dapp scope, so you can embed the analyzer, classifier and generated UI in your own app:

# analyze + classify a contract and render the generated UI
pnpm add @semantic-dapp/analyzer @semantic-dapp/classifier @semantic-dapp/renderer @semantic-dapp/components viem

# or drive it from the terminal
pnpm add -g @semantic-dapp/cli
semantic-dapp --help

Package	What it does
@semantic-dapp/spec	Schema, types and validation (contract model + manifest)
@semantic-dapp/analyzer	ABI normalization + standards analysis
@semantic-dapp/classifier	Turns analysis into a semantic manifest
@semantic-dapp/components	Trusted React UI components
@semantic-dapp/renderer	Renders a full app from a manifest + runtime
@semantic-dapp/execution · resolver · export · cli	Tx execution, contract resolution, portable bundles, CLI

Latest: 0.1.2 on npm. Still 0.x beta — APIs may shift before 1.0.

Try the demos

The live demo ships a mainnet USDC bundle (public RPC for reads; connect a wallet for writes). Click Load your contract to resolve an address or paste an ABI/artifact and run the generated UI on your contract — no Studio install required.

Local fixture demos (compiled Foundry contracts):

Demo	Contract	Shows off
Token	MockERC20	balances, transfer, approve, mint
Vault	MockVault (ERC-4626)	deposit / mint / withdraw / redeem
RWA	MockRWA	AccessControl roles + Pausable + mint/burn

See docs/demos.md for rendering them (optionally against a local Anvil chain), and docs/export.md for exporting and hosting your own.

What it understands today

Category	Supported
Token standards	ERC-20, ERC-2612, DAI-style permit, ERC-777, ERC-721, ERC-1155, ERC-4626
Token advisories	Rebasing / share-based, fee-on-transfer (admin-surface + Overview warn)
Governance	OpenZeppelin Governor; Compound-style Governor Bravo / Alpha
Access models	Ownable, AccessControl (roles), Pausable, upgradeable (+ diamondCut)
Proxies	EIP-1967, EIP-1167, Gnosis Safe, ERC-897, *Delegator, EIP-2535 diamonds
Enrichment	NatSpec + modifier / body-level access hints when source is available
Sources	Sourcify, block explorers (Etherscan v2 API), manual ABI/artifact

Don't see your pattern? The Raw tab always exposes every ABI function, and the rule engine is designed to be extended - contributions welcome.

Why Semantic Dapp vs…

	Etherscan Write	Bespoke frontend	Semantic Dapp
Time to a usable UI	instant	weeks	minutes
Understands roles/standards	❌	✅ (by hand)	✅ automatic
Simulation before signing	❌	maybe	✅
Safe defaults for admin actions	❌	maybe	✅
Self-host / export	❌	✅	✅
Stays in sync with the ABI	n/a	❌	✅

Design principles

• Deterministic-first - known standards recognized by rules, not by a generative model.
• AI-assisted, not AI-trusted - AI may propose; it never signs or hides uncertainty.
• Safe fallback - unproven meaning lands in Raw; writes there are fail-closed (Preview + execution envelope + confirm + typed CONFIRM), not one-click.
• Nothing is lost - every ABI function stays reachable.
• Trusted components - UI is built from verified components, not arbitrary generated React.
• Self-hostable by default - run locally, export, and host without any cloud.
• Open-source first - spec, analyzer, renderer and CLI are public from day one.

Monorepo layout

semantic-dapp/
├── apps/
│   ├── studio/            # import, review, preview, export (Vite + React)
│   └── generated-app/     # standalone template that renders a bundle
├── packages/
│   ├── spec/              # schema, types, validation (Zod + JSON Schema)
│   ├── resolver/          # address → ABI/source (Sourcify, explorer, proxies)
│   ├── analyzer/          # standards & capability detection
│   ├── classifier/        # operation type & audience routing
│   ├── components/        # trusted UI components
│   ├── renderer/          # manifest → React sections
│   ├── execution/         # viem/wagmi reads, simulation, writes
│   ├── export/            # portable SemanticBundle artifact
│   └── cli/               # semantic-dapp bundle | export | serve
├── contracts/fixtures/    # Foundry contracts (MockERC20, MockVault, MockRWA)
└── docs/                  # roadmap, ADRs, progress, demos

Status & roadmap

v0.1.2 - full pipeline + universal hardening (proxies/diamonds, more standards, tx preview, live load-your-contract). Still beta: while in 0.x, minor versions may include breaking changes.

• 🗺️ Roadmap · 📓 Changelog · 📊 Progress dashboard
• 🧱 Universal hardening backlog · 🎨 UX roadmap · 🧱 ADRs

Contributing

Issues, ideas, and PRs are all welcome - especially new standard/pattern detectors and UX polish. Start with CONTRIBUTING.md and CODE_OF_CONDUCT.md. Found a security issue? See SECURITY.md.

⭐ Star it, watch it, break it, tell us what's missing.

If Semantic Dapp is useful to you, a star is the single best way to help others find it.

License

AGPL-3.0-only - free to use, modify, and self-host; network-served modifications must share source.