docs: add Base Verify Onchain guide by patnir · Pull Request #1728 · base/docs

patnir · 2026-07-21T19:29:03Z

What changed? Why?

Adds a new Base Account guide, Verify Users Onchain, covering Base Verify Onchain: the extension of Base Verify to enforcement inside a smart contract. It carries Base Verify's two use cases onchain:

Sybil resistance via the deterministic identityHash (one real identity, one claim, across wallets), which the consumer contract dedupes on.
Identifying high-value customers via the contract's declared policy (provider + conditions, e.g. X followers >= 10,000 or an active Coinbase One membership), which Base checks against the user's real credential before signing.

Base signs a short-lived EIP-712 verification that the contract checks through the SignerRegistry, with no backend at claim time and without learning who the user is.

The guide covers:

Core concepts: identityHash, policy (provider + conditions), and how eligibility is enforced by Base
Architecture and claim flow
A consumer contract example extending BaseVerifyConsumer plus the frontend SIWE + fetch + claim steps
The POST /v1/onchain_verifications API reference and error handling
Supported providers/conditions and the security/privacy model

It pairs with the existing Verify Social Accounts guide (offchain) and is registered next to it in docs.json.

Notes to reviewers

Base Verify Onchain is currently testnet-only (Base Sepolia 84532); the guide states this and uses the deployed Base Sepolia SignerRegistry and example consumer addresses.
New page: docs/base-account/guides/verify-onchain.mdx; navigation entry added to docs/docs.json.

How has it been tested?

docs.json validated as JSON. Content and code examples were cross-checked against the shipped SignerRegistry / BaseVerifyConsumer contracts and the backend onchain_verifications endpoint.

cb-heimdall · 2026-07-21T19:29:08Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 1/2

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 1

Sum 2

kushagras481 · 2026-07-21T23:40:27Z

+**Base Verify Onchain enforces both directly in your contract.** The Base Verify backend signs a short-lived [EIP-712](https://eips.ethereum.org/EIPS/eip-712) verification that your contract checks in the same transaction as a deposit, trade, mint, or reward. No backend at claim time, and your contract never learns who the user is:
+
+- **Sybil resistance** comes from the `identityHash`. The same real-world identity always produces the same hash for your contract, regardless of which wallet it uses, so your contract counts each real person once.
+- **Quality gating** comes from your contract's policy. You declare a `provider` and `conditions` (for example, X followers ≥ 10,000 or an active Coinbase One membership); Base checks the user's real credential against them and only signs when they pass.


Quality Gating doesnt feel like the right term. I would lean towards something like "Policy Gating"

Good call

Renamed it to "Policy gating" throughout (title, description, and the concept bullet), tying it to the contract's declared policy.

cb-heimdall · 2026-07-22T00:32:52Z

Review Error for kushagras481 @ 2026-07-22 00:32:52 UTC
User failed mfa authentication, either user does not exist or public email is not set on your github profile. \ see go/mfa-help

ilikesymmetry · 2026-07-22T00:49:46Z

+
+**Base Verify Onchain lets your smart contract enforce "one real person, once" and gate on real-world traits, like an active Coinbase One membership. The check runs in your contract, so you don't run a verification backend.** Base signs a short-lived verification your contract checks in the same transaction as a claim, deposit, or vote.
+
+Live on Base Sepolia (testnet-only for now) while we gather feedback. Try the [live demo](https://base-verify-onchain-demo.vercel.app/), then send feedback through the [interest form](https://forms.gle/WTcuWyKkvUV6gGik6).


usually we put callouts like this in a component for more visual emphasis

Yes, you can use @patnir

Good call

Wrapped the Base Sepolia / feedback line in a <Note> callout.

youssefea · 2026-07-22T12:48:57Z

+- **Sybil resistance** comes from the `identityHash`. The same real-world identity always produces the same hash for your contract, regardless of which wallet it uses, so your contract counts each real person once.
+- **Quality gating** comes from your contract's policy. You declare a `provider` and `conditions` (for example, X followers ≥ 10,000 or an active Coinbase One membership); Base checks the user's real credential against them and only signs when they pass.
+
+**Example use cases:**


I don't think this is relevant. We already talk about the use cases in the previous bulletpoints. I'd remove this "Example use cases" section entirely

Good call

Removed the "Example use cases" section entirely.

youssefea · 2026-07-22T12:49:39Z

+
+### Verification
+
+A short-lived object signed by Base that your contract checks through the `SignerRegistry`. It is signed as EIP-712 typed data and contains:


Can you please hyperlink to these contracts if they're open sourced somewhere?

The contracts aren't open-sourced on a public repo yet, so there's nowhere public to link. The deployed SignerRegistry is viewable (verified source) via the Basescan address already linked in the table. I'll add source links once the contracts repo is public.

youssefea · 2026-07-22T12:50:36Z

+description: "Enforce Sybil resistance and quality gating inside any Base contract. Base signs a short-lived verification your contract checks in the same transaction as a claim, deposit, or vote, so one real identity counts once and only wallets that meet your bar can participate."
+---
+
+## TL;DR


Please call this something else not TL;DR, "Introduction" or "Summary"

Done

Renamed the section to "Summary".

youssefea · 2026-07-22T12:51:18Z

+
+**Base Verify Onchain lets your smart contract enforce "one real person, once" and gate on real-world traits, like an active Coinbase One membership. The check runs in your contract, so you don't run a verification backend.** Base signs a short-lived verification your contract checks in the same transaction as a claim, deposit, or vote.
+
+Live on Base Sepolia (testnet-only for now) while we gather feedback. Try the [live demo](https://base-verify-onchain-demo.vercel.app/), then send feedback through the [interest form](https://forms.gle/WTcuWyKkvUV6gGik6).


Yes, you can use @patnir

youssefea · 2026-07-22T12:53:42Z

+
+### Eligibility is enforced by Base
+
+Conditions are read from your contract onchain, never taken from the user. Base evaluates them against the user's real stored credential and only signs when they pass, so a user cannot strip or fake a condition to get a verification they are not entitled to.


What does "Base evaluates them" and "enforced by Base" mean? Is it Base Chain? or something else? Can you please be more precise? I think it's best to talk about the underlying mechanism

Good catch

"Base Verify" here means the Base Verify backend, the off-chain signer service, not Base Chain. Reworded the section to say so and to spell out the mechanism: it reads your contract's policy onchain via eth_call, evaluates it against the user's stored credential, and signs only when they pass.

Add an Apps guide for Base Verify Onchain, which extends Base Verify's Sybil resistance and policy gating to enforcement inside a smart contract. Base Verify signs a short-lived EIP-712 verification the contract checks via the SignerRegistry and dedupes on identityHash. Covers the summary/integration steps, core concepts, the claim flow, a consumer contract example, the POST /v1/onchain_verifications API, supported providers/conditions, and the security model. Registers the page in docs.json under Apps > Guides.

patnir force-pushed the docs/base-verify-onchain-guide branch 5 times, most recently from 08bb4ee to 8b9cef7 Compare July 21, 2026 19:42

kushagras481 reviewed Jul 21, 2026

View reviewed changes

patnir force-pushed the docs/base-verify-onchain-guide branch 14 times, most recently from d00e2b2 to dcdc04c Compare July 22, 2026 00:18

patnir requested a review from kushagras481 July 22, 2026 00:30

kushagras481 approved these changes Jul 22, 2026

View reviewed changes

ilikesymmetry reviewed Jul 22, 2026

View reviewed changes

patnir force-pushed the docs/base-verify-onchain-guide branch 4 times, most recently from 33c63a4 to 419d311 Compare July 22, 2026 16:43

patnir requested a review from ilikesymmetry July 22, 2026 16:53

youssefea requested changes Jul 22, 2026

View reviewed changes

base deleted a comment from cb-heimdall Jul 22, 2026

patnir force-pushed the docs/base-verify-onchain-guide branch from 38b860d to 583c7ca Compare July 22, 2026 20:21

patnir force-pushed the docs/base-verify-onchain-guide branch from 583c7ca to 1d85700 Compare July 22, 2026 20:22

patnir requested a review from youssefea July 22, 2026 21:24

youssefea approved these changes Jul 23, 2026

View reviewed changes


		Base Verify Onchain lets your smart contract enforce "one real person, once" and gate on real-world traits, like an active Coinbase One membership. The check runs in your contract, so you don't run a verification backend. Base signs a short-lived verification your contract checks in the same transaction as a claim, deposit, or vote.

		Live on Base Sepolia (testnet-only for now) while we gather feedback. Try the [live demo](https://base-verify-onchain-demo.vercel.app/), then send feedback through the [interest form](https://forms.gle/WTcuWyKkvUV6gGik6).


		### Verification

		A short-lived object signed by Base that your contract checks through the `SignerRegistry`. It is signed as EIP-712 typed data and contains:


		### Eligibility is enforced by Base

		Conditions are read from your contract onchain, never taken from the user. Base evaluates them against the user's real stored credential and only signs when they pass, so a user cannot strip or fake a condition to get a verification they are not entitled to.

Uh oh!

Conversation

patnir commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cb-heimdall commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cb-heimdall commented Jul 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

patnir commented Jul 21, 2026 •

edited

Loading

cb-heimdall commented Jul 21, 2026 •

edited

Loading