# About Umia
import { Callout } from "fumadocs-ui/components/callout";
Umia is the onchain value creation layer: a platform where tokens become financial primitives aligned with the value creation of the projects behind them.
## What Umia Is
Umia is the full-stack platform for funding, governing, and scaling onchain projects. Founders apply to launch and fund through Tailored Auctions, with projects selected through a Curated Track or a market-led Community Track. Once launched, founders build independently while tokenholders govern the project's noncustodial treasury through decision markets.
It combines four tools essential for any new project:
* **A legal framework built for tokens.** Every project operates within a **legal token wrapper** (a segregated portfolio under Umia's Cayman structure, built on the MetaLeX BORG framework) with one critical rule: decision-making authority is delegated to an onchain treasury contract, not the founding team. IP, operating team, and treasury sit under one entity; there is no foundation / DAO / labs split. See the [Legal Framework](/docs/legal-framework).
* **Programmable funding.** Fund your project through a [Tailored Auction](/docs/tailored-auctions): onchain price discovery with configurable phases, gating, and refunds. Proceeds land in the treasury contract, never a team wallet.
* **[Decision markets](/docs/decision-markets).** Strategic decisions are priced by markets rather than decided by opinion polls, and the resolved outcome binds the project like a board decision.
* **A [noncustodial treasury](/docs/treasury).** The team draws a monthly operating budget and keeps building; everything beyond it goes through governance. Holders never have to trust a multisig.
## Who It's For
* **Founders** who want to fund their project from their community without giving up operational control: crypto-native teams, AI-accelerated builders, and increasingly a much broader set of companies.
* **Tokenholders** looking for early access to new kinds of onchain projects, with a real say in direction.
* **Liquid funds** participating in larger Tailored Auctions.
## Founder-Led, Market-Driven
Umia's governance model is deliberately hybrid. Founders keep full operational agility: direction, product, shipping. At moments of strategic significance, the choice defers to decision markets, which price the impact of each possible outcome. Tokenholders act as a board of directors, not a C-suite: they set guardrails and validate direction, but don't run operations.
This is a third path between the two bad defaults: fund fast but lose control (DAO-style governance, memecoin launchpads), or keep control but lose alignment (traditional equity with a token bolted on).
## Umia as the First Project and Token
Umia runs as the first project on its own platform and legal wrapper, under the same rules every other project accepts. It has its own identity and aims to be self-sustaining after launch.
UMIA is the token of the Umia protocol. Holders govern the protocol the same way every project on the platform is governed: through decision markets. That covers the protocol's own noncustodial treasury, its configuration, including the fee switch on decision-market and swap activity, and its strategic decisions. Umia is the first project launched through its own stack, so UMIA operates under the same rules, the same treasury constraints, and the same binding outcomes as every token launched on the platform.
UMIA is also the working token of the Community Track. Curation markets are traded in UMIA: holders take positions that rank each cohort's applicants, and the top-ranked projects are admitted to launch. Projects admitted this way grant an allocation of their supply to the protocol treasury, which UMIA governance controls. Fees and allocations accrue to that treasury, and what happens with them is decided by the market of UMIA holders, not by the team.
# Decision Markets Dynamics
import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";
Decision markets are how an Umia project makes its strategic decisions: **governance by pricing outcomes instead of counting votes**. For every proposal, markets estimate what the project's token would be worth under each outcome, and the outcome the market values highest is the one that executes. This page covers the full lifecycle, the protections around it, and what these markets can control.
For a narrative walkthrough, see the [Anatomy of a Decision Market](https://www.umia.finance/blog/anatomy-of-dm) blog post.
## What a Decision Market Is
A decision market (a futarchic market) is a set of conditional markets, one per possible outcome of a proposal. Each conditional market trades the project's token *as if* that outcome were already decided. Instead of asking "what do you prefer?", the mechanism asks "what do you believe, enough to take a position on it?". Preferences are cheap; positions aggregate information.
## Anatomy of a Decision Market
This is the participant's view of the same mechanism: how you enter, what you see, how you trade, and how you leave.
### Entering: One Deposit, Every Outcome
To participate, you deposit either the project's token or the stablecoin the market is paired against. Your deposit is converted into **conditional tokens**: one version of your deposit for every outcome of the proposal, including **No-Op**, the outcome where no action is taken. Deposit 1,000 project tokens into a market weighing outcomes A and B, and you hold 1,000 conditional tokens in each of A, B, and No-Op. One deposit gives you a position in every possible future, so you can trade any outcome, or all of them, without splitting your capital across choices.
### Reading the Market
Every outcome has its own price chart, shown alongside the project token's **spot** price (its price in the regular, unconditional market). All conditional prices start at spot and diverge as trading accumulates. Two things to read:
* **Divergence from spot** is the market's estimate of an outcome's impact. If outcome A trades 20% above spot while outcome B trades 30% below, the market is pricing A as good for the project and B as harmful, and saying by roughly how much. This is the quantified signal votes never produce: each option's expected impact, comparable, before anything is implemented.
* **The TWAP** (time-weighted average price) of each outcome, viewable on the chart, is what actually decides the winner at close, not the last traded price.
The interface offers both an absolute price view and a view relative to spot.
### Trading Conditional Tokens
Once converted, you can buy and sell each conditional outcome at its current market price. Because your deposit exists in every outcome simultaneously, you can trade all conditional markets at once with your full deposit: position behind the outcome you believe in, hedge the ones you fear, and adjust as prices move. Only the winning outcome's trades materialize at resolution, so a position taken in a losing market carries no realized loss and no realized gain. That is what makes full coverage across outcomes rational: the cost of being positioned in an outcome that never happens is time, not capital. As a market approaches close, the leading outcome and spot tend to converge, since the leading conditional future is increasingly likely to become the actual one.
### Leaving Early
You don't have to stay until resolution. At any point while trading is open, you can convert conditional tokens back into regular ones by redeeming the same amount from every outcome, No-Op included: 100 redeemed from each side returns 100 regular tokens. This 1:1 equivalence between a token and its conditional versions holds for as long as trading is open, so entering a decision market never locks your assets behind the resolution date. If your trading has left you ahead in every outcome, that gain can be withdrawn before the market resolves at all. Once trading ends, redemption happens through settlement in the winning outcome instead.
## How a Proposal Resolves
**A proposal opens.** It states the action (say, increasing the monthly allowance to expand the team) and its conditions. The proposer locks a token stake, set per project, for the market's duration; it discourages spam proposals and is returned when trading ends.
**Conditional markets open.** One market prices the token conditional on the proposal passing, one conditional on it not passing (a proposal can carry more than two outcomes).
**Trading.** Over a window of three days by default (configurable per market), participants deposit the project token or the paired stablecoin, receive conditional versions in every outcome, and trade each conditional market according to how they believe that outcome would affect the project.
**Settlement.** The outcome with the highest TWAP at close wins, provided it beats the No-Op market (the status quo) by the project's configured threshold. Trades in the winning market settle, executed against liquidity the market escrowed from the project's treasury-owned spot pool position when it was created.
**Unwind.** Trades in losing markets unwind: those traders redeem their tokens as if nothing had happened. Taking a position on an outcome that doesn't occur costs nothing but time.
**Execution.** Once settled, anyone can trigger execution onchain (in practice, Umia's keeper does), and the treasury contract enforces the result. A resolved market has the standing of a board decision and binds the operating team (see [Markets as Your Board of Directors](/docs/markets-as-board)).
## Why Traders Participate
Participation is economically motivated: a trader who correctly anticipates a decision's impact benefits from having positioned accordingly, and idle conviction has an opportunity cost. That is the design intent, stated as mechanism: markets reward being right rather than being loud, which is what turns governance from a political ritual into a source of signal. For a founder, the output is the thing votes never provide: a quantified, comparable read on each option, delivered between sprints.
## What Decision Markets Control
* **Token issuance and burning**: supply changes of any kind (see [Ongoing Funding](/docs/ongoing-funding)).
* **Treasury spending** beyond the monthly allowance.
* **Team compensation**: packages, changes, and milestone structures (executed on [MetaVesT](/docs/metavest-vesting) rails).
* **Strategic actions**: acquisitions, pivots, major commitments.
* **Spinning out** of the Umia framework into a successor structure.
* **Liquidation or dissolution**: winding the project down entirely.
## Protections and Edge Cases
* **Manipulation.** Forcing an outcome by pushing a price is deliberately expensive: settlement is TWAP-based (averaged over time, not a snapshot), so a manipulator must hold a distorted price against everyone who profits from correcting it, for the whole window.
* **Minimum thresholds.** An outcome must beat the No-Op market by a meaningful margin to win; a coin-flip market doesn't execute anything.
* **Thin markets.** Early on, participation may be limited and signal quality lower; depth improves as the ecosystem grows. Founders should weight early results accordingly, and the threshold requirement protects against acting on noise.
* **No clear winner.** If no conditional market meaningfully beats No-Op, the status quo holds: the proposal simply doesn't execute.
* **Early-phase supervision.** During the early phase, team proposals require Umia approval before going live and community proposals are relayed through Umia; an emergency veto exists for exploits. All temporary and disclosed: see [Security and Audits](/docs/security).
## A Worked Example, Mechanism Only
A project proposes doubling its monthly allowance to hire two engineers. Two conditional markets open: *token-if-passed* and *token-if-not-passed*. Traders who believe the expanded team accelerates the project buy in the passed market; traders who believe the burn increase outweighs the gain buy in the not-passed market. Over three days, the passed market clears meaningfully above the not-passed market. At settlement the proposal passes: trades in the passed market settle, trades in the not-passed market unwind and redeem as if never made, and the allowance increase executes onchain against the treasury. The founder got a binding answer, and a readable one: the size of the gap between the two markets is the market's estimate of how much the decision matters.
# Overview
import { Cards, Card } from "fumadocs-ui/components/card";
import { ContactLinks } from "@/components/contact-links";
import { DocsAgentBanner } from "@/components/docs-agent-banner";
import { Bot, FileCode2, ShieldCheck, Wallet } from "lucide-react";
**Umia gives founders everything they need to launch, fund, and govern a token-native project.**
You get a legal wrapper, a token, a noncustodial treasury, community crowdfunding through onchain auctions, and governance through decision markets. All from one platform.
## Understand
Why Umia exists, and what it makes possible.
} description="The onchain value creation layer: what Umia is, how it works, and who it's for." />
} description="Why traditional funding and company formation can't keep pace with how fast teams ship today." />
} description="The broken trust contract between teams and tokenholders, and the three gaps behind it." />
} description="Early-stage incubations, fluid-capital projects, and agentic ventures." />
## Launch
Set up your project: legal structure, token, and treasury.
} description="Two paths to launch: the Curated Track (team-reviewed) and the Community Track (market-selected)." />
} description="Cayman-based legal wrapper for onchain-governed projects, built on MetaLex BORG." />
## Fund
Fund your project through community-driven token auctions.
} description="Onchain token launches powered by Uniswap v4 Continuous Clearing Auctions." />
} description="Privacy-preserving audience curation: participants prove they qualify without revealing their data." />
} description="Principles for a lean, aligned token structure: fluid capital, allocations, vesting, and the monthly allowance." />
## Govern
Run your project with decision markets, a transparent treasury, and structured token vesting.
} description="The division of authority: founders run operations, markets settle board-level decisions." />
} description="The full lifecycle: conditional tokens, reading the market, settlement, and protections." />
} description="How funds enter the treasury, the three ways they leave, and why both sides can rely on it." />
} description="The fluid-capital model: issuance by proposal, follow-on auctions, and revenue." />
} description="How founder, team, and investor tokens are locked in MetaVesT contracts and released over time or as price milestones are met." />
## Reference
} description="The UMIA token's role in governance, curation, and protocol economics." />
} description="Trust-minimized architecture, Certora audits, risk disclosures, and founder opsec." />
} description="The wallet you get on sign-in: sending and receiving funds, staying secure, with no seed phrase or prior crypto experience." />
} description="The implementation companion to the Umia Extension: architecture, privacy model, sybil resistance, and CCA behavior." />
} description="Smart contract reference for UmiaValidationHook: per-step bid eligibility, hookData format, and server permits." />
} description="Let AI agents discover, analyze, and trade decision markets and bid in token auctions through Base MCP." />
## Get in Touch
# Umia's Legal Framework
import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";
Every project created on Umia is established under a formal legal wrapper designed specifically for onchain-governed organizations. The framework provides legal personhood, enforceable governance, and accountability, all without traditional setup fees or extensive paperwork.
## Built on MetaLex BORG
Umia's legal wrapper is built on the [MetaLex BORG](https://cybercorps.metalex.tech) (Blockchain-native, Onchain-governed, Registered, General-purpose) framework: a Cayman Islands legal structure designed for organizations whose decision-making happens onchain.
Decision-making authority is delegated to an onchain treasury smart contract, not the founding team. If the team ignores a resolved decision, they are legally liable.
## The Segregated Portfolio Company (SPC) Structure
When setting up a project on Umia, it is established as a **Sub Company** (often referred to as SubCo) within the Umia Launcher SPC umbrella entity.
This structure provides the following benefits:
### Legal Personhood
Your project gains a formal legal identity, enabling it to sign contracts, enter into operating agreements, and hold intellectual property. This is essential for real-world business operations that go beyond purely onchain activity.
### Single-Entity Simplicity
Unlike traditional crypto project structures that require a foundation/DAO/labs split, Umia's SPC model keeps everything under one roof. The IP, operating team, and treasury all sit under the same entity, dramatically simplifying governance and operations.
### Low Setup Cost
There are no legal setup fees or paperwork required from founders. Umia handles the legal wrapper setup as part of the project creation process through the CLI.
## Founder Obligations
The founding team is legally required to abide by a set of rules defined at formation:
### Initial Disclosure
The team must specify the conditions, intellectual property, and assets under which the organization is created. This includes the team token allocation and the recurring monthly allowance (see the [Noncustodial Treasury](/docs/treasury) for how it works).
### Governance for Changes
To update the organization's parameters (for instance, to increase the monthly operational budget or expand the team), the founding team must create a governance proposal. The proposal is resolved by decision markets, typically within 72 hours.
### Binding Decisions
A proposal decided by the market becomes equivalent to a decision taken by a company's board of directors. The team must enact it or they may be held liable in a court of law. This is what transforms onchain governance from a suggestion poll into an actual decision driver.
## Tokenholder Protections
For tokenholders, the legal framework provides several critical protections:
* **Accountability for offchain actions.** Decisions made through decision markets are legally enforceable, not just advisory. The legal wrapper ensures the team must follow through.
* **Treasury control.** The noncustodial treasury is only controllable through decision markets. The team cannot unilaterally access funds beyond the pre-configured monthly disbursement.
* **Transparency requirements.** The operating agreement and its parameters are defined at formation and visible to all participants.
## Lifecycle Flexibility
Umia's legal framework is designed to support projects through their entire lifecycle:
### Wind Down (Liquidation)
At any point, a decision market proposal can liquidate the treasury and dissolve the organization. This is the ultimate protection mechanism for tokenholders.
If the project is no longer delivering value, the community can choose to distribute remaining assets pro-rata.
### Spin Off
Umia allows projects to spin out from the Umia legal framework toward any form they find best, from a completely private entity to an IPO-track company. This ensures ventures aren't locked into the Umia structure permanently.
### Pivot
Strategic pivots, including changes to the team's mandate, operational scope, or token utility, can all be proposed and resolved through decision markets.
## Next Steps
Learn how project funds are managed in the [Noncustodial Treasury](/docs/treasury).
# Curated and Community Tracks
import { Callout } from "fumadocs-ui/components/callout";
Umia provides two ways for teams to launch, each built for a different situation. If you have traction, a known team, or an existing relationship with the ecosystem, the **Curated Track** gets you evaluated and listed directly. If you're earlier, or you'd rather prove demand than credentials, the **Community Track** lets the market decide.
## The Curated Track
On the Curated Track, the Umia team evaluates and lists projects directly; there is no competitive market stage. It's designed for projects with existing traction, a known team, or a prior ecosystem relationship, and it's active from day one: the platform's earliest launches all go through curation, because they set the quality benchmark everything after them is measured against.
**What the application covers.** The intake asks for the full picture: your legal and entity status (existing entities, where IP sits, investor and token rights), your token structure if one exists, your funding history, product stage and traction, and your intended auction setup. Traction claims are verified independently, so self-reported numbers will be cross-checked. Vague answers slow the process more than honest "I don't know"s.
**Timeline.** After the working phase (due diligence, legal, tokenomics, auction configuration; see the [Legal Framework](/docs/legal-framework)), Curated projects go to the Curation Committee with a DD pack for an async review of about 5 working days before the launch date is set.
If you believe your project fits the Curated Track, reach out at [inbound@umia.finance](mailto:inbound@umia.finance).
### The Curation Committee
The committee owns the quality bar: it reviews Curated Track applications and launch-ready submissions, and it maintains the standard the track promises. Its judgment is the human layer on top of the DD process, and its approval is the last gate before a Curated launch.
## The Community Track
The Community Track is permissionless: projects self-apply, are grouped into cohorts, and compete in a **curation decision market**, where UMIA holders rank the cohort's projects by conditional price. The top-ranked projects are admitted to launch; the rest can reapply to a future cohort.
This does something no committee can: it prices admission. Instead of a panel's opinion, admission reflects what a market of platform stakeholders expects the project to contribute, with real positions behind the ranking rather than sentiment.
**The protocol allocation.** Projects admitted through the Community Track grant the Umia protocol treasury a fixed percentage of their token supply at TGE, enforced programmatically. That allocation is the price of admission, and it's also the alignment mechanism: the protocol receives an allocation in every project it admits, so the platform's stakeholders are ranking projects the protocol will hold an allocation in. Umia succeeds when its launches do, and the curation market makes that literal.
The Community Track requires the UMIA token to be deployed. Until then, all projects that apply are selected through the Curated Track.
## After Admission
The tracks converge. Whichever way you came in, what follows is the same: the formation flow (see the [Legal Framework](/docs/legal-framework)), your auction configuration ([Tailored Auctions](/docs/tailored-auctions)), and launch. The only structural difference at the end: Curated projects pass the Curation Committee's launch-ready review, while Community projects were already market-approved at admission.
# Markets as Your Board of Directors
Once your project is live, markets hold an essential role in your project: they are your **board of directors, not your C-suite**. They set guardrails and validate direction at the moments that matter; they don't run operations, and they can't micromanage you. This page explains the division of authority, why a market's decision actually binds, and what that means for how you run the project week to week.
## The Division of Authority
**Founders keep operational control.** Direction, product, hiring within budget, shipping, and every day-to-day call belong to you, not to a vote and not to a market. Your monthly operating allowance exists precisely so that routine execution never needs anyone's approval.
**Markets decide strategy.** Board-level matters go to decision markets: spending beyond the allowance, token issuance, strategic pivots, and, as the ultimate backstop, liquidation (the full list lives in [Decision Markets Dynamics](/docs/decision-markets#what-decision-markets-control)). If the decision would sit with a board in a traditional company, it sits with the market here.
For projects that work with AI agents, the same line applies one level down: agents execute and assist, humans decide, markets validate.
## Why a Market Decision Binds
This is the part that makes Umia different from every "governance" system that came before it: a proposal resolved by a decision market has the standing of a board resolution. The project's legal structure delegates decision-making authority to the onchain systems, so the operating team is legally bound to enact the outcome; ignoring it carries the same kind of exposure as a CEO ignoring their board. The mechanics live in the [Legal Framework](/docs/legal-framework); the practical consequence lives here: when the market resolves, the question is settled.
Your community knows their decisions are real, which is why they engage. And you know that a resolved market ends the debate, which is faster than a controversy that never closes.
## Why This Beats the Usual Options
DAO-style governance funds fast but drowns founders in votes while producing decisions nobody must follow. Traditional equity keeps the founder in control but leaves the community holding something with no say and no tie to the project. The board-not-C-suite model is the third path: you keep the agility, your community keeps real economic authority over the things that would concern a board, and the legal wrapper makes both halves enforceable. (The fuller comparison lives in [About Umia](/docs/about).)
# Token Vesting
import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";
Umia mints a project's **entire initial token supply once, up front**. Only the circulating float
is sold in the auction; the allocations for founders, the team, and early backers are locked in
vesting contracts and released gradually, as time passes or as price milestones defined in the
grant are met. Because the initial supply already exists in full, unlocks never create hidden
dilution, and any later issuance happens only through a decision market (see
[Ongoing Funding](/docs/ongoing-funding)). The app always shows **circulating vs. total** so the
locked overhang stays visible.
Umia handles this with **MetaVesT**, a well-established onchain vesting framework wired into the
project's noncustodial treasury and decision-market governance.
No founder or team member can move locked tokens early. Release follows the schedule that was
set, and any new grants or changes go through a decision market, never a unilateral action.
## How a Grant Works
Each grant is its own onchain **allocation** that custodies its tokens for the grant's lifetime.
Two independent conditions decide how much a beneficiary can actually take:
* **Vesting**: has the token been *earned* yet (by time or by price)?
* **Unlocking**: has it been *released* for withdrawal yet?
A beneficiary can withdraw the amount that has **both vested and unlocked**, minus whatever they
have already taken. Keeping the two axes separate lets a project, for example, vest tokens on a
fast schedule while releasing them more slowly.
## Two Release Schedules
**Over time.** Tokens vest linearly across a set duration. A grant can include a *cliff*, an
initial period where nothing vests, after which a lump becomes available all at once and the rest
continues linearly. This is the classic "1-year cliff, then linear" startup schedule.
**At a price.** A grant can carry *milestones* that unlock only once the token's market price
crosses a set threshold. The price used is a manipulation-resistant time-weighted average (TWAP),
so a momentary spike can't trigger an unlock. This ties rewards to value actually delivered, not
just time served.
A single grant can combine both: a steady time-vesting stream **plus** price milestones layered on
top.
A price milestone can only be met once the project's market is live (after the auction migrates
to a spot pool). There is no market price before then.
## The Three Kinds of Grant
MetaVesT supports three allocation types, so Umia can model the usual compensation structures:
* **Vesting allocation**: the common case. Granted tokens vest and unlock on the schedule above.
* **Token option**: the *right to buy* tokens at a fixed exercise price. The option vests over
time; the holder pays the exercise price to claim the underlying tokens.
* **Restricted token award**: tokens granted up front but subject to repurchase if conditions
aren't met; the restriction lapses on a schedule.
## When Grants Are Created
**At launch (genesis).** Founder, team, and early-backer grants are locked **before** the token
goes to auction, so only the remaining float is offered to the public. Once the project is live,
control over the grants routes to the project's governance; at no point can the launch operator
amend, terminate, or claw back an existing grant.
**After launch.** A new grant (a new hire, an advisor) is added through a **decision market**.
The treasury mints and funds the allocation only if the market approves the proposal, the same way
every other treasury action is governed.
## Claiming
Beneficiaries claim directly from their own allocation whenever something is withdrawable:
*withdraw* for a vesting grant, *exercise* for an option. Confirming a **price milestone** is
permissionless: anyone (or Umia's keeper, as a convenience) can flip a milestone to "unlocked"
once its TWAP threshold has been met.
## Seeing It in the App
The project's vesting surface shows, for each grant, how much has been **granted / vested /
unlocked / claimed / withdrawable**, the schedule behind it, and any price tranches measured
against the live TWAP, alongside the project-wide **circulating-vs-total** supply view.
For a live example, see [Umia's tokenomics grants](https://app.umia.finance/p/umia#tokenomics).
# Ongoing Funding with Fluid Capital
On Umia, the initial auction is the start of a project's funding life, not the end of it. Supply is a living instrument: more tokens can be minted later, for a follow-on auction, a program, or compensation, whenever a decision market supports the proposal. This is the **fluid-capital model**, and it changes both how you launch and how you grow.
At launch, it means you can start lean: no oversized treasury, no pre-allocated reserves for hypothetical futures, no dead-weight supply (see [Tokenomics Recommendations](/docs/tokenomics)). After launch, it means capital formation becomes a repeatable, governed action instead of a once-only event.
## The Mechanisms
* **Issuance by proposal.** The project can mint (or burn) tokens through a [decision market](/docs/decision-markets): to fund a new phase, compensate contributors, or seed a joint venture. The market prices the trade-off, and the mint happens only if the outcome clears.
* **Follow-on Tailored Auctions.** A project at a later stage can run another auction, with the same configurability as the first: phases, gating, caps, refunds. (See [Tailored Auctions](/docs/tailored-auctions).)
* **Revenue.** Product revenue can flow back into the same noncustodial treasury, extending runway without touching supply at all.
All three land in the same treasury under the same rules; nothing about ongoing funding creates a second, softer pot of money. (See [Noncustodial Treasury and Disbursements](/docs/treasury).)
## Why New Issuance Runs Through a Market
New issuance dilutes existing holders, and that's exactly why it runs through a decision market: the market prices the impact of the mint against the value of what it funds. A proposal with a vague use-of-funds story gets a market that reflects it. In practice, every ongoing-funding action should ship with the same rigor as the initial auction: what the capital is for, what it changes, and when it lands.
This inverts the usual dynamic. Elsewhere, dilution is something teams do to holders, announced afterward. Here it is something the holders' market approves in advance, or doesn't. Founders get a capital tool; holders get a structural guarantee that the tool can't be used quietly.
# New Project Types with Umia
Umia's components (the legal wrapper, Tailored Auctions, decision markets, and the noncustodial treasury) make possible new kinds of projects that previous structures could not start or govern for the long term.
From earlier-stage projects to agentic ventures, here are a few of the shapes this takes.
## Early-Stage Incubations
Projects that crowdfund from the public far earlier than traditional structures would allow. Because the team never has direct treasury access and major decisions require market approval, the community can support a project at a stage where, anywhere else, the only safeguard would be trust. The safeguards here are structural: rule-based capital, binding governance, an enforceable legal token wrapper. That makes viable a class of early project that previously had no credible way to fund publicly at all.
One such example of an early-stage incubation is **hackathon projects**. Usually, after a hackathon, projects hit a dead end: the team is adept at building, but funding and legal setup are a different skill entirely. With Umia, the facilitated legal wrapper and noncustodial treasury permit both an easier legal setup and higher confidence for people who wish to support it. You can read more about this example in [this post](https://x.com/umia_finance/status/2046730992694800803).
## Fluid-Capital Projects
Conventional token launches reserve large allocations upfront for everything they might ever need, which produces the low-float pattern and years of dead-weight supply. On Umia, more supply can be minted as you go through a follow-on auction, team performance packages, or an OTC round, whenever decision markets support the proposal. Projects launch lean and let future capital needs be future governance decisions.
## Agentic Ventures
Small teams, sometimes solo founders, that scale execution with AI agents across every function. Using standards like MCP and x402, agents can interact with the project directly, and Umia's structure is what keeps that safe: agents execute, humans decide, and decision markets and the noncustodial treasury rein in both. Under the legal framework, an agent can even act as a cofounder. Umia supports this natively with CLI, MCP, and agent skills (see the [Base MCP Plugin](/docs/technical-reference/base-mcp-plugin)), but it is one project type among several, not a requirement: much of what's being built is human teams moving fast.
# The Scaling Problem
We are living in a golden age for small teams building serious projects. Agentic workflows compress months of iteration into days. Onchain finance and neobanks put global payments and capital rails within anyone's reach. For a competent team, building has never been faster or cheaper.
What hasn't kept up is everything around the building: the legal structure, funding, and governance a serious project needs to scale. Execution has outrun funding and company formation, and the gap widens every year.
## The Formation Systems Are Built for a Slower Era
* **Funding** assumes months. SAFEs were designed for startups that need long cycles to iterate; a team that ships weekly can still spend a quarter or two closing a round.
* **Governance** assumes quarterly boards. Investor updates arrive monthly at best, and board-level input at a cadence designed for a different speed of company.
* **Community feedback** is unstructured: scattered opinions across social channels, with no way to tell signal from noise and nothing binding about any of it.
A founder today gets a choice between the slow-moving but established world of traditional finance, and the novel world of tokens, where tokenholders currently get few guarantees. Neither fits a project that moves at modern execution speed.
## Capital Is the New Bottleneck
When you can build in a week, the constraint stops being engineering. Time spent chasing capital and managing investor processes is time not spent building, and the equity cost of early rounds is calibrated to risk profiles from an era when execution itself was the risk.
## What Fast-Moving Projects Actually Need
Two things, and today's structures provide neither:
* **Speed.** Funding and governance that resolve in days, not quarters: an auction that can be configured and run onchain, and strategic decisions that settle between sprints.
* **Quantifiable strategic signal.** Not sentiment, but a real, comparable read on what the market believes each option is worth, with participants who profit from being right rather than loud.
Umia is built to close this gap end to end: capital formation that scales as fast, and as programmably, as the projects it supports. The next page covers why today's token launches don't solve it, and what a structure that does looks like: [What Most Tokens Miss](/docs/what-tokens-miss).
# Security and Audits
import { Callout } from "fumadocs-ui/components/callout";
Security on Umia starts at the architecture, not at a policy. The system is designed so that the answer to "what if the team goes rogue?" is structural: the team never has custody or unilateral control of funds, disbursements follow rules, and strategic decisions are validated by markets before they execute. Everything else on this page (audits, disclosure, operational hygiene) builds on that foundation.
## Trust-Minimized by Design
* **Noncustodial treasury.** Auction proceeds live in an onchain treasury contract. The operating team draws a pre-approved monthly budget; anything beyond it requires a governance decision. There is no admin path from the team to the funds.
* **Rule-based disbursements.** Payments and unlocks (including team vesting via [MetaVesT](/docs/metavest-vesting)) execute according to onchain schedules and conditions, not discretion.
* **Market-validated decisions.** Strategic actions pass through decision markets before execution, and a resolved decision binds the team legally (see the [Legal Framework](/docs/legal-framework)). Even governance itself is not a trust-me system.
## Audits
Umia's smart contracts are audited by [Certora](https://www.certora.com/), Umia's primary security partner and one of the leading security firms in the industry.
### Certora Security Assessment (April 2026)
Certora performed a manual, line-by-line review of Umia's full contract surface from **March 6 to April 8, 2026**: the Hub and launch contracts, the auction and its migration into Uniswap v4, the treasury with its allowance and disbursement logic, decision-market settlement and its TWAP oracle, governance execution, and vesting. The assessment combined design-level threat modeling against the protocol's core invariants (funds move only through resolved markets or pre-configured disbursements, winning outcomes are determined correctly from the TWAP, supply changes only through governance, access controls cannot be bypassed) with implementation analysis, and concluded with a follow-up review of the applied fixes.
At a high level:
* **20 findings: no critical, 2 high, 5 medium, 11 low, 2 informational.**
* **17 of the 20 are fixed**, with the fixes verified by Certora in a follow-up review. Both high-severity issues (settlement-related) are among the fixed and verified.
* **The remaining 3 are acknowledged**: accepted-risk items tied to trust assumptions the protocol already discloses by design, including the platform-level owner role that sits behind early-phase supervision (see [Noncustodial Treasury](/docs/treasury)).
## Umia Extension and zkTLS Security
The [Umia Extension](/docs/zktls-extension) generates eligibility proofs client-side, built on the Reclaim Protocol. What the proof guarantees: that a specific criterion was verified against a live TLS session with the data source. What it doesn't do: credentials, account contents, and identity never leave the participant's browser, are never linked to the wallet onchain, and are never held by Umia or the project.
## Risk Disclosures
Smart contracts can have bugs, audits reduce risk but don't eliminate it; token markets carry market and liquidity risk; and decision markets are an experimental governance mechanism whose behavior at scale is still being proven. Projects launching on Umia and participants interacting with them should understand all three. This section pairs with the legal disclosures in the launch documents; nothing here is a guarantee of safety or performance.
## Operational Security for Founders
The architecture removes custody risk from your community, but founders still hold keys that matter: the Operator signing key, and your multisig signers.
* Use hardware signers for every multisig participant; pick a signer count and threshold that survive one lost or compromised key.
* Treat the wallet that signed your legal pack as high-value: it's your identity as Operator.
* Phishing will target your launch: fake extensions, fake CLI packages, fake auction pages. Link only from your official channels, verify the extension ID, and assume anything DMed to you is hostile.
* Rotate and document access when team members change; the SubCo's records obligations make this a legal matter, not just hygiene.
## Reporting Vulnerabilities
If you discover a potential vulnerability in Umia's smart contracts or platform, please contact the team at [security@umia.finance](mailto:security@umia.finance).
Responsible disclosure is appreciated and may be eligible for a bug bounty.
# Tailored Auctions
import { Steps, Step } from "fumadocs-ui/components/steps";
Every Umia launch is funded through a **Tailored Auction**: Umia's configuration of Uniswap's **Continuous Clearing Auction (CCA)**, an onchain mechanism that discovers a token's market price over a set window and then seeds a Uniswap v4 pool with the proceeds at that discovered price. One mechanism handles the three things a launch actually needs: price discovery, distribution, and day-one liquidity.
## What a CCA Is
A Continuous Clearing Auction runs fully onchain over a set window (typically about a week). Each bid carries two things: a budget and a max price. Tokens release gradually according to the configured schedule, and at each clearing moment the released supply is allocated to the highest-max-price bids first; everyone clearing in that moment pays the same clearing price, and supply that goes unsold in one moment rolls forward to the next. The price is discovered gradually across the window: it moves as demand accumulates, and a bid stops filling if the clearing price rises above its max, with the unspent budget refundable. The rule for what you pay is simple: never above your max, and your average entry price is the average of the clearing prices while your bid was live, so earlier bids average lower.
The mechanisms it replaces make price a function of timing rather than demand. On a **bonding curve**, price is set by your position in the queue: earlier buyers get a mechanically lower price regardless of what demand actually is, so the launch turns into a rush for the front, and "price discovery" is really just a first-come race. A **Dutch auction** has the opposite pathology: the price descends until someone blinks, so participants are rewarded for waiting and punished for conviction, and the final price reflects who won the game of chicken more than what the market believes. Both compress the pricing decision into a single decisive instant, and both leak value to whoever plays the timing game best.
A CCA spreads the pricing decision across the entire window. The clearing price emerges from accumulated demand rather than from queue position or brinkmanship, and no participant can concentrate demand at a single decisive moment (which also removes most MEV). Because the level is discovered gradually, showing up early with conviction is structurally rewarded rather than punished: valuation matters more than timing. Parameters are immutable once set, so participants can verify the rules won't move mid-auction. When the auction closes, the proceeds bootstrap a Uniswap v4 pool at the discovered price, so the token starts trading immediately with real, treasury-owned depth rather than a market-making deal. (For the mechanism in full, see Uniswap's [CCA documentation](https://developers.uniswap.org/docs/liquidity/liquidity-launchpad/overview) and whitepaper.)
## How an Auction Unfolds
A Tailored Auction is built from **buckets** (called *steps* in the contracts): portions of the sale supply that release over time. An early-bid round, when configured, is simply the first bucket with an eligibility gate.
### Early Bid (Optional, Gated)
The auction can open with a gated bucket: an early-bid round for participants who prove eligibility through the [Umia Extension](/docs/zktls-extension) or a per-wallet allowlist. Early bids fill on the same clearing terms as every other bid, but because they enter while the clearing price is still at its earliest levels, they accrue the most exposure to the lowest prices of the auction. Per-wallet limits keep participation broad; a bidder who can't fill their full intended amount here can bid the remainder once the public auction begins.
### Public Window
The remaining supply releases across a sequence of buckets, each with its own duration, its own share of supply, and optionally its own eligibility gate. Early buckets can be gated tighter, later buckets open to everyone.
### Close and Migration
When the window ends, the auction finalizes its clearing state. Proceeds and the LP allocation seed the Uniswap v4 pool at the discovered price; participants claim their tokens.
## Who Can Bid in Each Round
Each bucket's access configuration is enforced onchain by the auction's validation hook. It can allow one or more of these paths, and every bid gets in through exactly one of them:
| Access rule | Who can bid | Cap rule |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Allowlist** | Wallets the team added for the round. | Each wallet has its own cap, set by the team and never published. |
| **Verified with the Umia Extension (zkTLS)** | Any wallet that proved one of the round's eligibility criteria through the [Umia Extension](/docs/zktls-extension). Meeting any single criterion unlocks bidding; nobody needs all of them. | The same per-wallet cap for every verified wallet, plus an optional auction-wide total for verified volume. |
| **Open, capped** | Everyone, subject to wallet-specific overrides. | A default per-wallet cap with overrides set by the team, covering the whole capped window rather than resetting each bucket. |
| **Open** | Everyone. | No per-wallet cap. |
For example, a round can accept both the allowlist and the extension; each bid then uses whichever path its wallet holds.
### Bidder Tags
The hub's Activity tab shows at most one tag next to each bid and each bidder:
* **Fund**: a label the team can assign to a wallet on the auction's allowlist. A label is set per auction and covers every round.
* **zkTLS**: the bid went through the Umia Extension. A bidder shows it when any of its bids did.
* **Angel**: any other wallet on the auction's allowlist.
A label always wins, and zkTLS wins over Angel. Everyone else carries no tag. What is never shown: a wallet's individual cap, which eligibility criterion a verified wallet used, or the names behind allowlisted wallets.
## What You Configure
This is the checklist a founder works through with the Umia team when setting up a Tailored Auction. Together these parameters are what makes the auction "tailored":
* **Supply on sale**: how much of total token supply the auction distributes, and how much is reserved for the LP seed.
* **Chain**: any EVM network where Uniswap v4 is deployed.
* **Rounds**: how many buckets, each one's duration and share of sale supply, which are gated and by what zkTLS or allowlist criteria, and per-wallet caps on gated ones. An early-bid round is the first bucket, gated. See [Who Can Bid in Each Round](#who-can-bid-in-each-round) for how each rule reads to bidders.
* **Price bounds**: the floor price the auction starts clearing at, and optionally a maximum accepted bid price.
* **Minimum proceeds (graduation threshold)**: the floor below which the auction fails to graduate and every commitment becomes refundable in full.
* **Bidding currency**: the base asset bids are placed in (USDC is the common default).
Durations, splits, and gating are all configurable; the defaults are starting points, not constraints. Aligning these choices with your allocation plan is covered in [Tokenomics Recommendations](/docs/tokenomics).
## Where the Stablecoins Go
When the auction graduates (clears the minimum proceeds), the cleared stablecoins split two ways. A portion pairs with the reserved LP token allocation to seed a Uniswap v4 pool at the discovered price; the LP position is owned by the project's noncustodial treasury, giving the token real, treasury-owned liquidity from day one. The rest flows directly into the project's noncustodial onchain treasury, never a team wallet, and the project's formation executes automatically at that same moment (see the [Legal Framework](/docs/legal-framework)). If the minimum proceeds aren't met, the auction doesn't graduate: every bid becomes refundable in full, no entity is formed, and no IP is assigned.
## Participating
Bidders participate onchain from a wallet. Depending on the launch, retail participants can also join with direct credit-card deposits (via MoonPay and Privy), so a gated community round isn't limited to crypto-native participants.
## What Umia Adds on Top of the Base CCA
* **Gated buckets via zkTLS**: eligibility-gated rounds through the [Umia Extension](/docs/zktls-extension), fully privacy-preserving.
* **Treasury integration**: proceeds settle into the decision-market-governed treasury, and formation is triggered by auction completion.
* **Any-stage flexibility**: first auction or follow-on for a live token, the same mechanism configures to fit. For projects with an existing token or prior auctions, see [Curated and Community Tracks](/docs/listing-tracks).
# Tokenomics Recommendations
import { Callout } from "fumadocs-ui/components/callout";
Your tokenomics are set before launch and reviewed with the Umia team during formation (see the [Legal Framework](/docs/legal-framework)). This page collects some of our recommendations for what works: the principles behind a token structure that keeps founder and community aligned long after the auction ends.
## Start Lean: The Fluid Capital Principle
The single biggest change from conventional token design: on Umia, **you don't need to pre-allocate supply for everything you might ever do**. Because supply decisions run through decision markets, more tokens can be minted later, for a follow-on auction, an ecosystem program, or team incentives, whenever the market supports the proposal.
That changes the starting shape. Conventional launches reserve large treasuries and future-use allocations upfront, which sit as dead weight from day one and force the low-float launch pattern that communities have learned to distrust. An Umia project can launch with a lean, honest distribution: sell what the auction needs, reserve what the near term requires, and let everything else be a future governance decision rather than a day-one lockup.
## Allocations: What to Size and How to Think About It
The buckets every project needs to size:
* **Public sale**: what the auction distributes. The more of the initial supply is allocated to the Tailored Auction, the easier it will be to convince the community to participate in this and following markets.
* **Liquidity**: the share reserved to seed the Uniswap v4 pool at the discovered price. Non-negotiable in structure, sized per launch.
* **Team**: kept honest by vesting (below). Oversized team allocations are the most common reason communities discount a launch before it starts. We recommend making this allocation as lean as possible, and then suggesting performance-based team compensation through decision markets.
* **Treasury / runway**: enough for a credible development runway at your monthly budget. Deliberately not more: an oversized treasury is exactly what the fluid capital model makes unnecessary.
* **Umia protocol allocation**: on the Community Track, a fixed share of supply granted to the Umia protocol treasury at TGE, enforced programmatically (see [Curated and Community Tracks](/docs/listing-tracks)).
The whole table must reconcile to 100% of supply before launch.
## Team Vesting
Vest the team on [MetaVesT](/docs/metavest-vesting) rails, and prefer **milestone-based unlocks over purely time-based ones** where you can define milestones that are objective and verifiable onchain. Time-based vesting says "we'll still be here"; milestone-based vesting says "we'll have done what we said". The second is a much stronger signal to your community, and it's enforced by condition contracts rather than promises.
Practical defaults: a meaningful cliff before anything unlocks, multi-year total duration, and unlock schedules that avoid concentrating large amounts into narrow windows. Performance-linked structures (including unlocks tied to sustained market measures) are possible and increasingly the norm on Umia, but their design and public description must go through Legal review first.
## The Monthly Allowance
Your treasury's monthly operating allowance is set at formation, with recipient addresses and purpose limits. Set it realistically: it's what you can spend without governance, and everything beyond it becomes a decision-market proposal. An allowance set too low turns routine operations into governance events; set too high, it undermines the credibility the noncustodial treasury exists to provide. Size it to your actual burn for development and go-to-market, and revisit it through governance as the project grows.
## Common Pitfalls
* **Over-allocating to the team.** The market reads it instantly, and it poisons everything downstream.
* **A thin community float.** If holders can't meaningfully participate in decision markets, your governance has no signal and your community has no voice.
* **No treasury runway.** Forced to return to governance for basics within weeks of launching.
* **Cliff dumps.** A large cliff that unlocks in one moment creates the exact event your unlock schedule exists to prevent. Smooth it.
* **Pre-allocated dead weight.** Reserving supply for hypothetical future programs, the fluid capital model exists so you don't have to.
All structures described here are illustrative and not financial advice. Final tokenomics, and every public description of them, must pass Legal review and follow Umia's token-communications guidelines: no price, return, or investment framing, anywhere, ever.
# Noncustodial Treasury and Disbursements
Every Umia project's funds live in a **treasury smart contract**, not in a team wallet and not behind a team multisig. The founding team has neither custody nor control at any point: money moves only by pre-set rule or by a resolved decision market. This page covers how funds get in, how they get out, and why both founders and holders can rely on it.
## How Funds Get In
Proceeds from your [Tailored Auction](/docs/tailored-auctions) flow directly into the treasury contract at settlement; there is no intermediate stop. Later inflows land in the same place: follow-on auctions, governance-approved issuance, and product revenue routed back to the project. One treasury, one set of rules, for the project's whole life. (See [Ongoing Funding with Fluid Capital](/docs/ongoing-funding).)
## How Funds Get Out
There are exactly three doors, and everyone can see all of them:
* **The monthly allowance.** A recurring budget for development and go-to-market, set at formation with recipient addresses and purpose limits. The team draws it automatically, with no proposal needed: this is what keeps founders moving at full speed.
* **Governance-approved disbursements.** Anything beyond the allowance (a large one-off spend, a new commitment, a compensation change) goes to a [decision market](/docs/decision-markets) and executes only if the market resolves in favor.
* **Liquidation.** At any point, a proposal can wind the treasury down and dissolve the project, distributing remaining assets pro-rata (see [Wind Down](/docs/legal-framework#wind-down-liquidation) in the Legal Framework). It's the tokenholder's ultimate backstop, and its existence is part of why supporting an early project on Umia is credible at all.
## The Rules Are Set at Formation, and Changed by Governance
At formation, the team specifies the conditions the entity operates under: recurring expenses, team allocation, and the allowance itself. Changing any of it, say, increasing the allowance to grow the team, is a strategic decision and goes through a decision market (resolving in roughly 72 hours). The treasury never depends on anyone's restraint; it depends on rules that are expensive to change quietly and impossible to change unilaterally.
Balances, inflows, and every disbursement are onchain and auditable by anyone, in real time. Your community doesn't have to ask how the money is being used, and you never have to write the awkward update explaining it.
## How We Make the Treasury Secure and Viable
During the protocol's early phase, Umia retains disclosed, temporary supervisory capabilities (proposal approval and relay, plus an emergency veto against exploits) that are progressively removed as the system matures. The same supervision is spelled out in [Decision Markets](/docs/decision-markets) and disclosed on [Security and Audits](/docs/security): the honest answer to "who can intervene?" is part of what makes the rest credible.
For founders: a liquid treasury usable from day one, a clear automatic budget, and no investor process standing between you and execution. For tokenholders: funds that cannot be quietly drained, spending that follows visible rules, and ultimate control sitting with the market rather than with promises. Neither side is trusting the other; both are trusting the same contract they can both read.
## Key Principles for Founders
**Plan your budget conservatively.** Set an initial monthly allowance that covers your core needs. It's easier to propose an increase with demonstrated traction than to start too high.
**Communicate proactively.** Tokenholders govern through decision markets, and well-informed markets make better decisions. Regular updates on spending, milestones, and plans build trust and improve governance outcomes.
**Use proposals strategically.** Don't submit treasury proposals for trivial amounts; batch related requests when possible. Each proposal consumes community attention and decision market liquidity.
**Embrace transparency.** The noncustodial model is your greatest asset for building trust. Lean into it: share treasury dashboards, spending breakdowns, and roadmap updates publicly.
# Umia Token
import { Callout } from "fumadocs-ui/components/callout";
import { Cards, Card } from "fumadocs-ui/components/card";
import { MarketResult } from "@/components/docs/market-result";
Umia is the first project launched on its own platform, and $UMIA is the first token launched through the Umia architecture. The token governs the Umia Protocol itself: holders direct protocol strategy and the noncustodial treasury through decision markets, control the fee switch, and curate which projects launch through the Community Track. Umia runs on the same stack every project on the platform relies on, so the team building the governance system is also subject to it.
Umia was incubated by Chainbound and now operates as its own entity, Umia, S.P., a segregated portfolio of Umia Launcher SPC (see the [Legal Framework](/docs/legal-framework)).
For the latest information on the token, treasury composition, and more, see the [Umia project page](https://app.umia.finance/p/umia) on the Umia app.
## The UMIA Token's Role
$UMIA is the central coordination mechanism for the protocol. Through decision markets, holders govern four things:
### Protocol Treasury Management
Auction proceeds flow directly to the noncustodial protocol treasury. Whether it's swapping treasury assets, changing the disbursement amount, or a one-off funding, any use of the treasury outside the pre-set monthly disbursement requires prior approval from a decision market.
The [first Umia decision market](https://app.umia.finance/p/umia/market/treasury-capital-yield) is an example: it decided how to allocate the treasury's USDC. Full deployment across Aave and Steakhouse won by 6.75% over Do Nothing and executed onchain on Sep 19, 2026.
### Strategic-Level Decisions
High-level governance decisions, such as significant changes in strategic direction, conditional minting of new tokens, protocol upgrades, or the project's dissolution, require a decision market to execute.
For the first 6 months after launch, no liquidation proposals can be introduced.
### Community Track Curation
All Community Track curation markets are paired against $UMIA. When a cohort of projects applies to launch through the Community Track, $UMIA holders participate in a decision market that ranks which projects are most likely to strengthen the protocol's ecosystem.
To be eligible, a project grants the Umia protocol treasury a fixed percentage of its token supply at TGE, enforced programmatically. Holders are therefore ranking projects the protocol will hold an allocation in: Umia succeeds when its launches do. (See [Curated and Community Tracks](/docs/listing-tracks).)
The Community Track is not yet open. The first cohorts launch through the Curated Track from Q4 2026.
### Protocol Fee Governance
The protocol controls the **fee switch**, which determines the fees the protocol accrues across the platform:
* **Spot swap fees** on each project's spot market
* **Conditional swap fees** on decision-market trading
* **Future fee structures**, such as project-creation fees, as new protocol features are introduced
$UMIA holders govern these parameters through decision markets.
## Tokenomics
$UMIA has a total supply of 50M and a launch supply of 40M.
| Bucket | Tokens | % of total | Unlock |
| -------------------- | ---------- | ---------- | ----------------------------------------- |
| Token sale (auction) | 17,300,000 | 34.6% | Fully liquid at TGE |
| Backers | 10,150,000 | 20.3% | 36-mo vesting, catch-up after 12-mo cliff |
| Performance reserve | 10,000,000 | 20.0% | Conditional, TWAP price triggers (below) |
| Uniswap LP pool | 3,500,000 | 7.0% | Seeded protocol-owned liquidity at close |
| Protocol treasury | 3,050,000 | 6.1% | Unlocked, governed by decision markets |
| Service providers | 3,000,000 | 6.0% | 36-mo vesting, catch-up after 12-mo cliff |
| Team | 2,500,000 | 5.0% | 36-mo vesting, catch-up after 12-mo cliff |
| Incentives | 500,000 | 1.0% | Unlocked at launch |
### Team Performance Reserve
The 10M performance reserve is minted onchain but locked in [MetaVesT](/docs/metavest-vesting), outside the 40M launch supply. It unlocks only when a sustained 30-day TWAP of $UMIA reaches a multiple of the auction close price:
| Price multiple (vs TGE) | Released | Tokens |
| ----------------------- | -------- | ------ |
| 2x | 10% | 1.0M |
| 5x | 20% | 2.0M |
| 10x | 20% | 2.0M |
| 20x | 30% | 3.0M |
| 50x | 20% | 2.0M |
A tranche whose threshold is never sustained never unlocks and never enters circulation.
Of the 12.5M tokens allocated to the team and service providers, 10M (80%) are tied to these performance triggers.
## The Launch
$UMIA launched through a Tailored Auction on Base, the same mechanism every project on Umia uses (see [Tailored Auctions](/docs/tailored-auctions)).
| Parameter | Detail |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Dates** | Aug 26 to Sep 2, 2026: 3-day early bid (zkTLS-verified wallets and ecosystem funds) + 4-day public auction |
| **Tokens at auction** | 17.3M (34.6% of supply) |
| **Floor / cap** | $0.12 / $0.36 |
| **Clearing price** | $0.36 (hit the cap; bids trimmed pro rata, unspent budgets refunded) |
| **Minimum raise** | $2M, met |
| **Base currency** | USDC on Base (card deposits via Privy) |
| **Vesting** | None, fully liquid at close |
At close, roughly 20% of proceeds were paired with the LP allocation to seed a UMIA/USDC pool on Uniswap v4, owned by the treasury. The remaining proceeds went to the noncustodial treasury under the programmatic monthly cap.
## Monthly Disbursement
The treasury releases an automatic monthly disbursement of **$120K**, enforced by smart contracts. This lets the team operate while leaving most of the treasury under noncustodial control. Any change to the cap, and anything beyond it, requires a decision market. The current planned breakdown is as follows:
* **Staff (\~$57K).** Protocol development and day-to-day operations.
* **Subsidies & support to projects (\~$22K).** Direct support for projects launching through Umia.
* **Events & ecosystem (\~$17K).** Outreach, community activations, co-marketing with pipeline projects.
* **Infrastructure & tooling (\~$8K).** Systems that keep the platform running.
* **Contingency (\~$17K).** Kept as a visible line.
This breakdown is indicative, not a hard categorisation of the monthly disbursement.
## See Also
} description="The UMIA token, treasury, and every protocol contract, by network." />
} description="Trust-minimized architecture, the Certora audit, and risk disclosures." />
} description="The full Certora report for the Umia Protocol." />
} description="Umia, S.P.'s formation summary on MetaLex." />
} description="How MetaVesT locks the team, backer, and performance-reserve allocations." />
# What Most Tokens Miss
If tokens are such a powerful capital-formation tool, why do serious teams hesitate to launch one? Because **the trust contract between teams and tokenholders is broken onchain**. Holders fund a team and then hold something with little real control and no enforceable recourse. Everything else on this page is a symptom of that.
## Today's Options, and Where They Fall Short
* **Memecoin and creator launchpads**: no credibility, no decision-making mechanism, MEV-infested. Holders have zero say over fund management. Almost always the wrong venue for a serious team.
* **Permissionless ICO platforms**: no standard for legal agreements or treasury management. Works for niche and side projects; rarely for serious, long-term projects.
* **Curated platforms**: a real step up, but expensive, late-stage, and still trust-based. Teams use them as an expansion round after years of building, not as a first auction, and they don't align holders in long-term governance.
Each solves a piece; none fixes the underlying relationship.
## The Three Gaps
**The custody gap.** Funds sit in team-controlled wallets and multisigs. Every promise about how they'll be used is exactly that: a promise.
**The governance gap.** Coin-voting without treasury control is an onchain opinion poll. There's no economic incentive to participate thoughtfully, no enforcement when the team ignores the result, and almost no recourse for offchain actions. Engagement decays accordingly.
**The alignment gap.** A project takes off and its token doesn't move, because nothing ties the project's performance to the token. At best the token is an operational burden; at worst, a branded memecoin. Even the project's strongest believers have no reason to hold it.
## What's Actually Needed
* Capital control that is **rule-based and fully noncustodial**: funds follow rules, not trust.
* Governance that is **economically motivated and enforceable**, onchain and legally.
* A structure where **the token is the project**: everything under one legal wrapper, built token-first, so there is nothing for performance to leak into instead.
## How Umia Closes Each Gap
* Custody → the [noncustodial treasury](/docs/treasury): the team draws a budget, everything else goes through governance.
* Governance → [decision markets](/docs/decision-markets) with real positions behind them, controlling a real treasury, with outcomes that bind.
* Alignment and enforcement → the [legal wrapper](/docs/legal-framework): resolved decisions are board decisions, not suggestions, and IP, team, and treasury sit under the one structure the token governs.
The net effect: early public crowdfunding becomes viable for projects that today would be considered too early, because the safeguards are structural rather than reputational. The next page covers what that makes possible: [New Project Types with Umia](/docs/project-types).
# Umia Extension and zkTLS
import { Callout } from "fumadocs-ui/components/callout";
Most launches face an ugly trade-off: either do an open token sale full of bots and buyers without conviction, or a private sale that limits the participation of your community. The Umia Extension removes the trade-off. It lets your auction be tailored to exactly the kind of participants you want, while those participants prove they qualify without revealing their identity, their accounts, or their data.
A launch that starts with people who understand and believe in the project builds a healthier holder base from day one, and early access is itself the incentive that brings those people in.
## What zkTLS Is
zkTLS is a way to prove a fact from any website that sits behind a login: a balance, a score, an account age, a credential, using a zero-knowledge proof. The proof confirms the criterion is met without revealing the underlying data, and without linking that data to the participant's wallet.
The Umia Extension is built on the [Reclaim Protocol](https://docs.reclaimprotocol.org/). If a website has information behind a login, a proof can be generated about it: the participant logs into the site as themselves, and the protocol produces a cryptographic attestation about the specific fact being checked, nothing more.
## How the Extension Works
The [Umia Extension](https://chromewebstore.google.com/detail/umia/ejcaahfcaaiblipldkfijdcbannidbdd) is a standard Chrome extension: the client tool participants use to generate proofs during an auction. It sits between the participant's data source and the auction's eligibility check.
From the participant's side the flow is short: install the extension, open the auction's gated round, log into the site the criterion refers to, and wait a few seconds while the proof is generated in the browser. The auction contract sees a valid proof of eligibility; it never sees the account, the login, or the data behind it.
For the implementation walkthrough (architecture, privacy model, sybil resistance), see [Reclaim zkTLS Integration](/docs/technical-reference/reclaim-integration).
## What Can Be Verified
Any claim that can be proven in the browser over a TLS connection. In practice that means almost anything behind a login. Some examples of the shape of criteria founders can set:
* **Product usage**: has this person actually used a product like yours? For example, how many API credits they've spent on an AI platform.
* **Platform activity**: are they active on prediction markets, or on the platforms your project builds for?
* **Trading history**: can they prove their exchange account cleared a certain lifetime trading volume, without revealing the account?
* **Account age and KYC reuse**: reuse the fact that another platform already verified this person, as an anti-sybil measure, without collecting anyone's documents yourself.
If there's something specific you want to verify (your product's usage or anything else), you can [contact the Umia team](https://www.umia.finance/contact) to get it added to the Extension.
## Why This Matters for Your Launch
* **You reach the right community, not the fastest bots.** Eligibility is about who the person is as a user, not who got in the queue first.
* **No public allowlist.** You never hold a list of names or accounts, and participants never expose themselves to have their eligibility checked. With this you get to verify things that users might not want to associate with their wallet, such as accounts or scores.
* **Early access becomes a reward for the people you care about.** A gated early round gives your actual users a reason to become holders before the general public.
* **Sybil resistance without friction.** Criteria tied to real, hard-to-fake account history filter out multi-wallet farming better than captchas or forms.
## How It Plugs into Your Auction
Eligibility criteria are defined when your Tailored Auction is configured, and they gate specific parts of it: typically an early-bid round or specific supply buckets, each with its own caps. The rules plug directly into the auction's configuration alongside phases, caps, and refund logic. See [Tailored Auctions](/docs/tailored-auctions) for how the rounds themselves work.
Criteria are set per launch and published before the gated round opens, so participants know what qualifies and can generate their proof in advance.
## Security and Trust Assumptions
Proof generation happens client-side; sensitive data does not leave the participant's browser and never touches the chain. What the proof guarantees, and the trust assumptions behind the underlying protocol, are covered in [Security and Audits](/docs/security).
# Base
import { Callout } from "fumadocs-ui/components/callout";
import { AddressTable, NetworkCard } from "@/components/docs/address-table";
Base is where Umia launched and where the UMIA token lives. Every address on this page links to Basescan, and Umia-authored contracts link to their source in the public [protocol repository](https://github.com/umiafinance/protocol).
Copycat pools and lookalike contracts exist on Base. Only the addresses listed here are part of the protocol, and the same address can hold a different contract on another network.
## Protocol contracts
Shared infrastructure that every venture on Umia runs on. Deployed once per chain and owned by the protocol.
### Core
### Markets and oracles
### Launch
### Vesting
### Identity verification
### Uniswap V4
Canonical Uniswap deployments on Base. Umia does not own or upgrade these.
### Money token
## UMIA venture contracts
Umia launched on its own platform. These contracts belong to the UMIA venture, created through UmiaHub as venture #7. Use them when interacting with the UMIA token, its treasury, or its markets.
# Contract Addresses
import { Callout } from "fumadocs-ui/components/callout";
import { NetworkList } from "@/components/docs/address-table";
Umia Protocol is deployed on each network below. Every deployment is independent, with its own UmiaHub, ventures, and markets. Pick a network to see its contracts.
The same address can hold a different contract on each network. `0x5597…29F6` is UmiaMarketCore on Base and UmiaMarketStake on Robinhood Chain. Always check an address against the page for the network you are using before interacting with it.
The UMIA token and its venture contracts live on [Base](/docs/contract-addresses/base#umia-venture-contracts).
# Robinhood Chain
import { Callout } from "fumadocs-ui/components/callout";
import { AddressTable, NetworkCard } from "@/components/docs/address-table";
Robinhood Chain runs its own Umia deployment, with its own UmiaHub, ventures, and markets. Every address on this page links to the Robinhood Chain explorer, and Umia-authored contracts link to their source in the public [protocol repository](https://github.com/umiafinance/protocol).
Several Umia contracts share an address across networks but hold a different contract on each. `0x5597…29F6` is UmiaMarketStake here and UmiaMarketCore on Base. Only use an address from the page for the network you are on.
## Protocol contracts
Shared infrastructure that every venture on Robinhood Chain runs on. Owned by the protocol.
### Core
### Markets and oracles
### Launch
### Vesting
### Identity verification
### Uniswap V4
Uniswap V4 deployments on Robinhood Chain. Umia does not own or upgrade these.
### Money token
# Base MCP Plugin
import { Callout } from "fumadocs-ui/components/callout";
Umia ships a [Base MCP](https://docs.base.org/ai-agents) plugin that lets any
AI agent trade decision markets (futarchy) and participate in token auctions.
The agent reads public Umia APIs, builds **unsigned** `{ to, value, data }`
calldata via the auth-free `/api/v1/calldata/*` endpoints (or the
`npx umia-cli@latest` thin client), and submits everything through Base MCP
`send_calls`. It never signs or broadcasts on its own, and never touches a
private key.
The canonical plugin file is hosted at:
**[`umia.finance/base-mcp/umia.md`](https://umia.finance/base-mcp/umia.md)**
It is authored against the upstream
[plugin spec](https://github.com/base/skills/blob/master/skills/base-mcp/references/plugin-spec.md)
and targets `skills/base-mcp/plugins/umia.md` in
[`base/skills`](https://github.com/base/skills). Until it ships there as a
native plugin, install it as a **custom plugin**:
## Install as a custom plugin
1. Install the Base MCP skill if you haven't:
`npx skills add base/skills --skill base-mcp`.
2. Download the plugin file and drop it next to the skill's other plugins
(`skills/base-mcp/plugins/umia.md` in your skill directory), or simply
paste its contents into the conversation and tell the agent to treat it as
a Base MCP plugin:
```bash
curl -sL https://umia.finance/base-mcp/umia.md \
-o skills/base-mcp/plugins/umia.md
```
3. Smoke-test the CLI path: `UMIA_ENV=testnet npx umia-cli@latest auctions`.
Custom plugins are **not** in Base MCP's hosted `web_request` allowlist.
On chat-only surfaces (Claude.ai, ChatGPT) `web_request` will reject
`api.testnet.umia.finance` / `api.mainnet.umia.finance` until the plugin
ships natively. The consumer-surface user-paste fallback is GET-only,
so the `POST /api/v1/calldata/*` builders cannot run there at all. Use a harness
with its own HTTP tools or a shell (Claude Code, Codex, Cursor): the
plugin's Surface Routing section prefers those paths automatically.
## What agents can do
* **Markets**: list open decision markets, read proposals and TWAP prices,
enter (`split`), buy/sell proposal conviction with quoted price impact,
merge back, claim settlements, and permissionlessly settle ended markets.
* **Auctions**: list live auctions, read clearing price / proceeds /
leaderboard analytics, bid on permissionless steps (with automatic tick-grid
price alignment and Permit2 approval batching), and claim. The claim batch
composes the required exits first, so unspent-currency refunds and token
transfers land in one `send_calls`.
* Verification-gated auction steps (zkTLS / server permit) are detected and
routed to the Umia app instead of failing onchain.
Everything runs on the environment selected by `UMIA_ENV`. Default
**testnet** (Base Sepolia). Mainnet currently hosts auctions only.
# Bid Validation
import { Callout } from "fumadocs-ui/components/callout";
import { Mermaid } from "@/components/mermaid";
{/* bid-validation-source: e406975c17db1a90ea6e3713c06802d21ecf0f0e876485f156fdbc569c5bcfe0 */}
{/* The Foundry CI job runs smart-contracts/check-bid-validation-doc.sh, which fails when the hook
sources change without this page. Update the charts to match, then run `just bid-validation-doc --update`. */}
The CCA calls `UmiaValidationHook.validate` on every bid, and `validate` is the only way a credential reaches the hook. These charts follow the contract branch by branch, so every revert a bid can hit appears once. Nodes that start with **Revert** name the error; rounded nodes let the bid through. For the `hookData` formats and the owner functions in detail, see [Validation Hook](/docs/technical-reference/validation-hook).
The CCA wraps any revert from the hook as `ValidationHookCallFailed(reason)`, so a failed bid carries the hook's error inside.
## Setup and configuration
Unpaired, validate() allows every bid"]
cca["Create the CCA with this hook as its validationHook
The CCA's hook is immutable"]
pair["setCCA(cca), once, later calls are no-ops
Caches the CCA step schedule, reverting on empty,
misaligned, zero-length or more than 256 steps"]
config["Configure steps: owner calls, in any order, at any time
(see the table below)"]
activate["Optional, per step: multicall(requireStepNotStarted(step),
the step's setters, setVerifyEveryBid(step, true))"]
check{"Step already started, disabled,
or without a proof or permit gate?"}
rejected["Revert the whole batch:
StepAlreadyStarted or NoGateConfigured"]
on["The step verifies every bid"]
off["Cleared by setVerifyEveryBid(step, false) at any time,
or by disableStep / disableStepBatch"]
deploy --> cca --> pair --> config --> activate --> check
check -- yes --> rejected
check -- no --> on --> off
`}
/>
| Owner call | Effect |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `setCCA(cca)` | Pairs once and caches the CCA schedule. Later calls are no-ops. |
| `enableStep` / `enableStepBatch` | Turns enforcement on and sets the step's providers, which are its proof gate. An empty list means no proof gate. |
| `disableStep` / `disableStepBatch` | Turns enforcement off and clears the step's verify-every-bid flag. |
| `setStepProviders` / `setStepProvidersBatch` | Replaces a step's providers. |
| `addStepProviders` / `removeStepProviders` | Adds or removes single providers. Removing one that is absent reverts `ProviderNotFound`. |
| `enableStepPermit` / `disableStepPermit` | Turns a step's permit gate on or off. |
| `setSigner(signer)` | Sets the permit signer. `address(0)` disables every permit. |
| `setVerifyEveryBid(step, on)` | On only before the step starts, with the step enabled and gated. Off at any time. |
| `setStepMaxBidAmount(step, amount)` | Per-wallet zk cap at a step. 0 means no cap. |
| `setZkGlobalMaxBidAmount(amount)` | Auction-wide zk cap. 0 means no cap. Settable before pairing. |
| `setMaxBidPrice(q96)` | Bid price cap, which must sit on the CCA tick grid. 0 means no cap. |
| `unregister` / `unregisterBatch` | Clears standing registration (see below). |
| `clearIdentity(providerHash, identityHash)` | Frees an identity slot. |
| `multicall(calls)` | Runs owner calls atomically. Leading with `requireStepNotStarted(step)` makes a late-mined batch revert. |
Everything except `setSigner`, `setZkGlobalMaxBidAmount`, `setCCA`, `clearIdentity` and `multicall` reverts `NoCCA` before pairing.
## Validating a bid
The CCA calls validate(maxPrice, amount, owner, sender, hookData)
sender pays, credentials and caps bind to owner"]
paired{"Hook paired with a CCA?"}
caller{"msg.sender is the paired CCA?"}
price{"maxBidPrice set and
maxPrice above it?"}
resolve["Resolve the current step: the CCA's step,
or a forward scan of the cached schedule
when the CCA's step is stale at a boundary"]
inStep{"Current block inside a step?"}
enabled{"Step enabled?"}
gates{"Which gates does the step have?
proof gate: providers set
permit gate: permit enabled"}
vebOpen{"Step verifies every bid?"}
standing{"Standing registration applies?
step does not verify every bid, has a proof gate,
and owner is registered at this or an earlier step"}
empty{"hookData empty?"}
pick{"Take the permit path?
permit gate, and hookData starts 0x01
or the step has no proof gate"}
eCaller["Revert CallerNotCCA"]
ePrice["Revert MaxBidPriceExceeded"]
eNoGate["Revert NoGateConfigured"]
eEmpty["Revert ServerPermitRequired (permit gate only),
ProofRequired (proof gate only) or NotVerified (both gates)"]
caps["Enforce zk caps"]
allow1(["Allow"])
allow2(["Allow"])
allow3(["Allow"])
allow4(["Allow: public step"])
allow5(["Allow"])
permitPath[["Permit path"]]
proofPath[["Proof path"]]
bid --> paired
paired -- no --> allow1
paired -- yes --> caller
caller -- no --> eCaller
caller -- yes --> price
price -- yes --> ePrice
price -- no --> resolve --> inStep
inStep -- no --> allow2
inStep -- yes --> enabled
enabled -- no --> allow3
enabled -- yes --> gates
gates -- neither --> vebOpen
vebOpen -- yes --> eNoGate
vebOpen -- no --> allow4
gates -- "proof, permit or both" --> standing
standing -- yes --> caps --> allow5
standing -- no --> empty
empty -- yes --> eEmpty
empty -- no --> pick
pick -- yes --> permitPath
pick -- no --> proofPath
`}
/>
### Permit path
hookData = 0x01 + abi.encode(permitStep, nonce, deadline, signature)"]]
p1{"Payload well-formed?
0x01 prefix, canonical ABI head, signature within the payload"}
p2{"Current step or permitStep verifies every bid,
and permitStep is not the current step?"}
p3{"permitStep after the current step?"}
p4{"permitStep has the permit gate, signer set,
deadline not passed, nonce unused?"}
p5{"EIP-712 ServerPermit(owner, permitStep, nonce, deadline, amount)
signed by the signer?"}
p6["Burn the nonce, emit PermitConsumed"]
ePermitReq["Revert ServerPermitRequired"]
eMismatch["Revert CredentialStepMismatch"]
eHigh["Revert PermitStepTooHigh"]
ePermit["Revert ServerPermitNotEnabled, SignerNotSet,
ExpiredDeadline or PermitAlreadyUsed"]
eSig["Revert InvalidSignature"]
allowP(["Allow, permit bids skip the zk caps"])
start --> p1
p1 -- no --> ePermitReq
p1 -- yes --> p2
p2 -- yes --> eMismatch
p2 -- no --> p3
p3 -- yes --> eHigh
p3 -- no --> p4
p4 -- no --> ePermit
p4 -- yes --> p5
p5 -- no --> eSig
p5 -- yes --> p6 --> allowP
`}
/>
### Proof path
hookData = proofStep (32 bytes) + abi.encode(Reclaim.Proof)"]]
q1{"Payload is a proof?
not 0x01, at least 32 bytes"}
q2{"Current step or proofStep verifies every bid,
and proofStep is not the current step?"}
q3{"proofStep after the current step?"}
q4{"Current step verifies every bid?"}
consume["Consume a bid proof at the current step
(see proof checks)"]
register["Register the owner from proofStep
(see proof checks)"]
zk["Enforce zk caps"]
eProofReq["Revert ProofRequired"]
eMismatch["Revert CredentialStepMismatch"]
eHigh["Revert ProofStepTooHigh"]
allowQ(["Allow"])
start --> q1
q1 -- no --> eProofReq
q1 -- yes --> q2
q2 -- yes --> eMismatch
q2 -- no --> q3
q3 -- yes --> eHigh
q3 -- no --> q4
q4 -- yes --> consume --> zk
q4 -- no --> register --> zk
zk --> allowQ
`}
/>
### zk caps
Proof bids and bids covered by standing registration count toward both caps. Permit bids never do: the API enforces permit caps when it signs.
and emit ZkGlobalBidAccrued"]
z3{"Step cap set, and the owner's step total + amount above it?"}
z4["Accrue the owner's step total (only while the step is capped)"]
eGlobal["Revert ZkBidExceedsGlobalCap"]
eStep["Revert ZkBidExceedsStepCap"]
start --> z1
z1 -- yes --> eGlobal
z1 -- no --> z2 --> z3
z3 -- yes --> eStep
z3 -- no --> z4
`}
/>
## Proof checks
A proof is either a registration proof, sent inline on an ordinary step, or a bid proof, sent inline on a step that verifies every bid. The signed context message tells them apart, so neither can stand in for the other.
for this chain, auction, step and amount?"}
r1{"Signed context message is register:CHAIN:AUCTION:NONCE
for this chain and auction?"}
eB1["Revert BidProofFromFuture"]
eB2["Revert BidProofExpired"]
eB3["Revert BidProofContextMismatch"]
eR["Revert RegistrationProofContextMismatch"]
bidIn --> b1
b1 -- yes --> eB1
b1 -- no --> b2
b2 -- yes --> eB2
b2 -- no --> b3
b3 -- no --> eB3
regIn --> r1
r1 -- no --> eR
subgraph shared ["Shared checks for both kinds"]
s2{"contextAddress is the owner?"}
s3{"The proof's step has providers,
and the proof's providerHash is one of them?"}
s4{"Identity (provider + extractedParameters)
claimed by another wallet?"}
s5["Claim the identity for the owner on first use
(skipped when the proof has no extractedParameters)"]
s6{"Reclaim witness signatures valid?
Stateless, no shared replay registry is written"}
eS2["Revert ContextAddressMismatch"]
eS3["Revert ProviderNotFound or ProviderHashMismatch"]
eS4["Revert IdentityAlreadyClaimed"]
eS6["Revert from the Reclaim verifier"]
s2 -- no --> eS2
s2 -- yes --> s3
s3 -- no --> eS3
s3 -- yes --> s4
s4 -- yes --> eS4
s4 -- no --> s5 --> s6
s6 -- no --> eS6
end
b3 -- yes --> s2
r1 -- yes --> s2
b4{"Bid proof already consumed?"}
eB4["Revert ProofAlreadyUsed"]
b5(["Mark it consumed, emit ProofVerified
Never registers the wallet"])
r2(["Registered from the proof's step, emit Registered and ProofVerified
Reusable: registration keeps no used-proof record"])
s6 -- "yes, bid proof" --> b4
s6 -- "yes, registration proof" --> r2
b4 -- yes --> eB4
b4 -- no --> b5
`}
/>
## Registration and unregistering
the first time their bid carries a valid registration proof"]
later(["Later bids at this and later ordinary proof-gated steps
need no credential"])
un["unregister(user) / unregisterBatch(users): owner, needs pairing"]
un1["Standing registration cleared"]
un2(["The next bid needs a proof again. Any valid registration proof,
including the earlier one, registers the wallet again"])
un3["Not cleared: the identity slot, consumed bid proofs,
burned permit nonces, zk bid totals"]
ci["clearIdentity(providerHash, identityHash): owner"]
ci1(["Frees the identity slot so another wallet can claim it"])
reg --> later
un --> un1 --> un2
un1 -.-> un3
ci --> ci1
`}
/>
## Where credentials come from
The Hub picks `hookData` from the step's gates. A step that verifies every bid gets a new permit while the wallet's allowance covers the bid, and a new bid proof otherwise. An ordinary step gets nothing once the wallet is registered onchain, then a stored registration proof, then a permit.
>API: POST /api/v1/hub/server-permit/sign (auction, step hint, amount, walletAddress)
Note over API: walletAddress must be linked in Privy (a read at most 30 s old, outage returns 503),
screening, server-resolved step, cap policy, live onchain gate check
API-->>W: EIP-712 ServerPermit(wallet, step, nonce, deadline in 5 min, amount)
W->>C: submitBid(maxPrice, amount, owner, 0x01 + permit)
else zkTLS proof
W->>API: POST /api/v1/hub/zktls/proof-request (provider, contextMessage, walletAddress)
Note over API: walletAddress must be one of the caller's linked wallets
API-->>W: Signed Reclaim request with contextAddress = wallet
W->>R: Prove the account, contextMessage register:... or bid:...
R-->>W: Reclaim proof
opt Registration proof on an ordinary step
W->>API: POST /api/v1/hub/zktls/verify (stores registration proofs only)
end
W->>C: submitBid(maxPrice, amount, owner, proofStep + proof)
else Already registered, ordinary proof-gated step
W->>C: submitBid(maxPrice, amount, owner, empty hookData)
end
C->>H: validate(maxPrice, amount, owner, sender, hookData)
H-->>C: Returns, or reverts and the bid fails
`}
/>
## Views
| View | Answer |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorizesWithoutCredential(step, user)` | False out of range. True on a disabled step. False on a step that verifies every bid. Otherwise `isVerified(step, user)` when the step has a proof gate, else true only when it has no permit gate. |
| `isVerified(step, user)` | Whether the user is registered at `step` or an earlier step. |
| `verifiesEveryBid(step)` | The step's verify-every-bid flag. |
| `isStepEnabled(step)` / `isStepPermitEnabled(step)` / `getStepProviders(step)` | The step's gates. |
| `expirationBlock()` | End block of the highest gated step, meaning enabled with providers, a permit gate or verify every bid. 0 when no step is gated. |
| `getSteps()` / `cca()` / `signer()` / `maxBidPrice()` | The cached schedule and settings. |
| `stepMaxBidAmount(step)` / `zkBidTotal(wallet, step)` / `zkGlobalMaxBidAmount()` / `zkGlobalBidTotal()` | zk caps and running totals. |
| `isPermitNonceUsed(nonce)` / `identityOwner(providerHash, identityHash)` | Burned permit nonces and identity slots. |
| `requireStepNotStarted(step)` | Reverts `StepAlreadyStarted` once the step has started. |
| `supportsInterface(id)` | CCA validation-hook introspection, `IUmiaValidationHook`, `IMaxBidPriceValidationHook`, `IGatedValidationHook` and `IVerifyEveryBidHook`. |
# Reclaim zkTLS Integration
import { Callout } from "fumadocs-ui/components/callout";
import { Mermaid } from "@/components/mermaid";
This page is the implementation-level companion to [Umia Extension and zkTLS](/docs/zktls-extension). It explains how Umia integrates Reclaim proofs into Tailored Auctions, how the privacy model works in practice, how sybil resistance is enforced, and what this changes for the Continuous Clearing Auction (CCA).
## Why We Use Reclaim
Tailored Auctions need a way to make statements like "this round is for GitHub contributors" or "this bucket is for a specific community" without turning the auction into a centralized KYC flow.
Reclaim gives Umia a way to:
* gate early auction steps by offchain credentials;
* bind a proof to the bidder's wallet so it cannot be replayed by someone else;
* preserve public onchain execution of the auction itself;
* add provider-scoped sybil resistance for gated rounds;
* keep the CCA's price discovery and settlement logic unchanged.
## What Umia Actually Integrates
At a high level, Umia combines five layers:
| Layer | Role |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Reclaim provider + witnesses | Produce and attest to a zkTLS proof about some offchain account or activity |
| Umia app frontend | Requests proofs, stores them locally, and attaches them to bids as `hookData` |
| Umia API | Creates proof-request configs, verifies proofs off-chain, stores proofs, computes identity hashes, and serves eligibility |
| `UmiaValidationHook` | Verifies wallet binding, provider compatibility, monotonic eligibility, and onchain identity ownership |
| CCA / Validation Router | Calls the hook on every bid; accepts or rejects the bid based on verification state |
The important design choice is that **Reclaim is the proof system, while Umia is the auction-specific policy layer**. Reclaim proves something about offchain data. Umia decides which proofs are accepted for which auction step and how that affects bid eligibility.
## Architecture Diagram
Defines lock requirements, provider IDs,
and provider hashes per step"]
CLI["Umia CLI / Deploy Flow
Deploys the hook, pairs it to the auction,
and enables step-level providers"]
VH["UmiaValidationHook
Wallet binding, provider checks,
monotonic registration, identity gate"]
CCA["Continuous Clearing Auction
Normal CCA pricing, clearing, and settlement
with gated bid admission"]
RV["Reclaim Verifier Contract
Checks witness signatures and proof validity"]
HUB["Umia App UI
Requests proof configs, stores proofs locally,
and submits bids with hookData"]
API["Umia API + DB
Eligibility, proof-request config, proof storage,
identityHash, permit wallets, hook metadata"]
EXT["Reclaim Browser Extension
Runs the provider verification flow
in the user session"]
PROV["Offchain Provider
GitHub, token source, reputation system, etc."]
FO -->|"configure auction policy"| CLI
CLI -->|"deploy, setCCA, enableStepBatch"| VH
CLI -->|"create auction with hook"| CCA
CCA -->|"validate hookData"| VH
VH -->|"verifyProof"| RV
HUB -->|"eligibility + proof APIs"| API
HUB -->|"proof request / proof result"| EXT
EXT -->|"provider verification flow"| PROV
HUB -->|"submitBid with hookData"| CCA
API -.->|"optional pre-submit checks"| VH
`}
/>
## Sequence Diagram
>H: Open gated auction
H->>A: GET eligibility(auction, wallet)
A-->>H: Requirements, current step, proof/permit state
U->>H: Click Verify
H->>A: POST /proof-request
A-->>H: Serialized config with wallet context
H->>E: Start verification in extension
E->>P: Provider proof flow
P-->>E: Proof material
E-->>H: Reclaim proof
H->>A: POST /verify with proof
note right of A: Checks providerHash, wallet context, identityHash
A-->>H: verifiedFromStep or error
U->>H: Place bid
H->>C: submitBid(maxPrice, amount, owner, hookData)
C->>V: validate(owner, hookData)
note right of V: Resolve step, check provider, claim identity, store result
V->>R: fetchWitnessesForClaim(...)
R-->>V: Expected epoch witnesses
note right of V: Verify signatures; a bid proof is consumed, a registration proof stays reusable
`}
/>
For ordinary early-bid steps, verify off-chain, store the proof in the backend, then send that proof inline in `hookData` when bidding. Steps configured with `verifyEveryBid` generate a fresh, amount-bound proof during each bid attempt (or use an accepted server permit) and ignore standing registration.
## How We Integrate Reclaim Into an Auction
### 1. We deploy and pair the hook
Each gated auction gets a `UmiaValidationHook`. The hook is paired to a single CCA via `setCCA(address)`.
That pairing matters because the hook caches the CCA's step ranges and resolves the current step from block number during `validate()`.
### 2. We configure allowed Reclaim providers per step
Auction steps are configured with Reclaim `providerHash` values, plus human-readable `providerId` labels for UI/indexing.
In practice, the CLI computes or accepts provider hashes and then calls:
* `enableStepBatch(stepIndices, providerHashesPerStep, providerIdsPerStep)` during deployment;
* `addStepProviders(...)` or `setStepProviders(...)` for later updates.
This is how a founder says, for example, "step 0 accepts GitHub provider X" while later steps may accept a broader or different set.
### 3. We expose readable requirements to the app
The API/indexer layer stores a human-readable description per provider and per step. That is what powers the lock-requirements UI in the app.
### 4. We mint proof requests server-side
The Umia app never gets the Reclaim app secret directly.
Instead, the API creates the proof request using Reclaim credentials and returns a serialized config to the frontend. During that step, Umia binds the bidder wallet into the proof context:
```text
ReclaimProofRequest.init(appId, appSecret, providerId)
proofRequest.setContext(walletAddress, "Auction verification")
```
That wallet binding is critical. It means the proof is not just "someone has this credential". It is "this credential was issued for this wallet context".
### 5. We verify off-chain before the user bids
When the extension returns a proof, the API validates the proof off-chain and applies Umia-specific policy checks:
* the auction must actually use a zkTLS hook;
* the requested step must be enabled;
* the proof's `providerHash` must match one of the step's accepted providers;
* the proof's `contextAddress` must equal the authenticated wallet;
* the proof must pass Reclaim verification;
* the proof is normalized to the earliest step that accepts that provider.
That last point is important for monotonic access. If a proof qualifies a user for an earlier locked step, Umia records the earliest valid step so later bids can reuse that stronger eligibility.
### 6. We store the proof and reuse it at bid time
After off-chain verification, the proof is stored in the API database and cached locally in the browser. On bid submission, the frontend prefers, in order:
* an in-memory freshly verified proof;
* a locally cached stored proof;
* a backend-stored proof fetched for the wallet;
* a server permit, if that step supports permits;
* empty `hookData` if the wallet is already onchain verified.
## What Goes Onchain
The bid path still ends at the CCA's normal `submitBid(...)` call, but now `hookData` may carry verification material.
For Reclaim proofs, Umia encodes:
```text
hookData = abi.encodePacked(uint256 proofStep) ++ abi.encode(Reclaim.Proof)
```
The validation hook then:
1. resolves the current auction step;
2. checks whether that step is gated;
3. checks whether the wallet is already verified from an earlier step;
4. if not, decodes `hookData` and verifies the proof for `proofStep`;
5. stores `verifiedFromStep` for monotonic access.
This means verification is part of bid admission, not part of price formation.
## How This Affects CCA
Reclaim changes **who can submit a valid bid in a given step**, but it does **not** change the core economic mechanics of the auction.
| CCA surface | Effect of Reclaim integration |
| -------------------------------- | ---------------------------------------------------------------------------- |
| Bid entry | A bid may require valid `hookData` before it is accepted |
| Clearing price | Unchanged |
| Fill logic | Unchanged |
| Settlement and liquidity seeding | Unchanged |
| Auction step timing | Same CCA steps, but some steps are gated |
| User state | Once verified from step `N`, the user stays eligible for `N` and later steps |
In other words, Reclaim adds an admission-control layer around the auction. It does not fork or replace the CCA itself.
## The Privacy Model in Practice
### What is private
Umia does not require public KYC and does not need a real-world legal identity to gate an auction. The bidder proves eligibility through a signed Reclaim proof that is bound to their wallet.
### What is intentionally bound
The wallet address is intentionally inserted into the proof context. That is how the system prevents replay across wallets.
### What is not guaranteed by Umia alone
Privacy depends on what the Reclaim provider includes in the signed `context` and `extractedParameters` fields.
If the provider emits a privacy-preserving pseudonymous identifier, Umia can enforce one-wallet-per-identity without learning a raw username. If the provider emits a raw handle, then that handle may be present in the proof payload and privacy is correspondingly weaker.
Umia's integration is privacy-preserving by architecture, but not magically data-free. The actual privacy level depends on provider design. The safest provider design is to expose only the minimum fields needed for wallet binding, provider selection, and sybil resistance.
## The Privacy-Preserving OPRF Piece
The sybil-resistance design is built around a provider-scoped stable identity, represented in Umia as:
```text
identityHash = keccak256(providerHash || extractedParameters_substring)
```
Two details matter here:
* `providerHash` namespaces the identity by provider/version, so the same source account under two different providers does not collide;
* `extractedParameters_substring` is taken verbatim from the signed Reclaim context both off-chain and onchain, so both layers compute the same `identityHash` byte-for-byte.
Why this is useful:
* if Reclaim provides an OPRF-derived pseudonymous identifier, the same real-world account maps to the same stable provider-scoped identity without exposing the raw account identifier;
* Umia only needs the stable pseudonym to enforce one-wallet-per-identity;
* the contract and API never need a traditional user database keyed by a Web2 username.
What Umia does **not** do is run the OPRF ceremony itself. Umia consumes the signed output that comes back inside the Reclaim proof context and then derives `identityHash` from it.
## Sybil Resistance
Umia enforces sybil resistance in two places.
### Off-chain gate
When the API stores a proof, it computes `identityHash` and tries to claim that identity for the current hook.
It uses:
* a transaction-level advisory lock on `(hookId, identityHash)`;
* a unique database index on `(hook_id, identity_hash)`;
* same-wallet re-verification logic that replaces older proof rows.
If a different wallet already claimed that identity, the API rejects the proof with a conflict instead of letting the user proceed to bid.
### Onchain gate
The validation hook independently enforces the same identity claim onchain:
* `_identityToUser[providerHash][identityHash]` stores the wallet that owns that provider-scoped identity;
* first claim wins;
* re-verification by the same wallet is idempotent;
* a different wallet reverts with `IdentityAlreadyClaimed(...)`.
This means the backend improves UX and reduces wasted bid attempts, while the contract remains the final enforcement layer.
One caveat: the onchain identity gate only applies when the provider's proof context includes `extractedParameters`. For a provider that emits none, the contract skips the identity claim and sybil enforcement rests on the off-chain gate alone; this is another reason provider design matters (see the privacy nuance above).
## Submission Modes
Umia supports two verification modes in the same hook:
| Mode | How it works | Typical use |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------ |
| Inline Reclaim proof | Bid carries `proofStep + Reclaim.Proof` in `hookData` | Current default app UX |
| Server permit | Bid carries an EIP-712 permit in `hookData` (inline-only; no pre-submission path) | Admin-curated or fallback allowlists |
The same auction can mix Reclaim steps and permit-enabled steps.
## Why the Monotonic Model Matters
Verification is monotonic: if a wallet verifies for step `0`, it is also valid for steps `1`, `2`, `3`, and so on.
That matters because Tailored Auctions often want a funnel like:
* early blocks reserved for a narrow cohort;
* later blocks widened to a broader cohort;
* final blocks fully open.
Without monotonic registration, users would need to re-prove eligibility at every step transition. With monotonic registration, one strong proof unlocks the rest of the auction path that should logically include that user.
## Tradeoffs and Design Intent
This integration intentionally chooses:
* onchain enforcement over trust in the frontend;
* wallet-bound proofs over reusable anonymous bearer credentials;
* provider-scoped sybil resistance over fully open one-wallet-many-wallet behavior;
* optional backend prechecks for UX, while keeping the contract as the source of truth.
The tradeoff is that privacy quality depends on provider design, and the first gated bid carries more verification data than a fully open bid.
## Summary
Reclaim gives Umia a way to add offchain audience targeting to an otherwise fully onchain auction.
* Reclaim proves eligibility.
* Umia decides which providers are allowed for which auction steps.
* The API binds proofs to wallets, stores proofs, and blocks obvious sybil reuse early.
* The validation hook enforces the same rules onchain during `validate()`.
* The CCA keeps its native auction mechanics; only bid admission changes.
For the user-facing overview, see [Umia Extension and zkTLS](/docs/zktls-extension). For the contract-level interface, see [Validation Hook](/docs/technical-reference/validation-hook).
# Smart Wallet
import { Callout } from "fumadocs-ui/components/callout";
Umia gives you a **wallet** the moment you sign in. No app to install. No seed phrase to write down. No prior crypto experience required.
This page has three parts, depending on where you're coming from:
1. **The basics**: what everyone needs to know to start using Umia.
2. **If you've used crypto before**: how Umia's wallet differs from what you're used to.
3. **For developers**: the implementation details.
## The basics
### Signing in
You sign in with Google or GitHub, just like any other app (if you already have a crypto wallet, you can connect that instead). There's nothing to install, nothing to write down, no recovery phrase to memorize.
The account you signed in with is what gets you back to your wallet later. If you sign out and come back tomorrow with the same account, you'll find everything exactly where you left it.
### Your wallet address
Umia creates a unique address for you. Think of it like an account number for receiving money. It shows up at the top of the app and in the Deposit screen. Share it with anyone who wants to send you funds.
The same login always gives you the same address. It doesn't change.
### How you pay for things
Most apps in this space make you hold a separate currency just to pay small fees for every action. Umia doesn't. Whether it's placing a bid, entering a market, or claiming a reward, the fee is handled for you. Most of the time, using Umia feels free.
You don't need to top up anything special ahead of time. Show up with the amount you want to spend, and you can use it.
### Adding funds
Open **Deposit** from your account menu. You have two ways to put money in:
* **Buy**: use a card, Apple Pay, or bank transfer to buy funds directly into your wallet.
* **Receive**: copy your address and send funds from another wallet or exchange.
Funds show up in your balance within seconds of arriving.
### One click, one confirmation
Some actions need several steps behind the scenes. Umia handles that for you. You'll see one confirmation, sign once, and either the whole thing happens or none of it does. There's never a half-finished state where some steps ran and others didn't.
### Getting your money back out
You're not locked in. You can withdraw or move your funds at any time. From your account menu, you can also export the key that controls your wallet. If you ever decide to leave, you take your wallet with you.
### If you lose access to your login
Recovery runs through whatever login method you used. Lost your Google account? Go through Google's recovery. Same for GitHub. Once you're back in, your wallet is back.
Your wallet's safety is tied to the account you signed in with. Keep 2FA on, don't reuse passwords, and treat that account the same way you'd treat any account that holds money.
### Common questions
**Where is my money actually stored?**
In your wallet, an account tied to your login. Umia doesn't hold it; you do.
**What if I lose my phone or computer?**
As long as you can sign back in with the same login from any other device, you're fine. Nothing important is stored on the device itself.
**What if a transaction fails?**
Your funds stay exactly where they were. The app tells you what went wrong in plain language.
**Is it safe?**
Your wallet is as safe as the account you signed in with. Keep that account secure (strong password, 2FA) and you're in good shape.
## If you've used crypto before
Your Umia wallet is a **smart wallet**. Specifically, an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account (the [Kernel](https://docs.zerodev.app/) implementation) controlled by a [Privy](https://docs.privy.io/wallets/using-wallets/evm-smart-wallets/overview)-managed embedded signer. Two practical differences from a typical EOA:
* **You don't hold gas tokens.** A paymaster sponsors gas on every transaction; you never need the network's native token to do anything.
* **Transactions are batched atomically.** One UserOperation replaces the approve-then-exec chains that normally need multiple confirmations. Either the whole batch lands or the whole batch reverts.
The **address shown everywhere in the app is the smart-account address**, not the signer. The signer is an EOA that Privy manages for you; it lives at a different address and you don't normally interact with it directly. Send funds to the smart-account address (the one shown in Deposit), not to the signer.
**Can I bring my own wallet?** Yes. Connect MetaMask, Rainbow, or any injected wallet from the login screen. You lose the smart-wallet features (batching and sponsored gas) and pay gas in the network's native token as usual, but everything else works the same way.
**Can I export?** Yes, from the account menu. Export gives you the signer's private key. That signer controls the Kernel smart account, so importing it into tooling that understands Kernel lets you keep using the same smart-account address from elsewhere.
**Why doesn't my balance match what I see on a block explorer?** You're almost certainly looking at the wrong address or the wrong chain. Make sure you're using the smart-account address (the one in Deposit), on the network Umia is running on, not the signer EOA.
**Do transactions show up as normal `eth_sendTransaction` calls onchain?** No. They're UserOperations submitted via a bundler and routed through the account's `EntryPoint`. Explorers with AA support (including ERC-4337 indexers on Etherscan and similar) will decode them; older views just show the bundler's wrapper transaction.
## For developers
Implementation lives in `web/hub/`:
* `components/providers.tsx`: Privy + `SmartWalletsProvider` + paymaster context wiring
* `hooks/use-active-wallet.ts`: routes the "active" address to smart-account vs signer EOA; source of truth for every address-keyed read in the app
* `hooks/use-smart-write.ts`: `writeContract` for single calls, `sendCalls([...])` for atomic batched UserOps on the smart wallet; on the EOA fallback path, caller-agnostic batches collapse into one Multicall3 `aggregate3` transaction and the rest run as sequential per-call transactions
* `lib/paymaster.ts`: Pimlico sponsorship policy wiring consumed by `SmartWalletsProvider`
External references:
* [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337): account-abstraction standard
* [Kernel (ZeroDev)](https://docs.zerodev.app/): smart-account implementation
* [Privy smart wallets](https://docs.privy.io/wallets/using-wallets/evm-smart-wallets/overview): provider integration
* [Pimlico](https://docs.pimlico.io/): bundler and paymaster
# Validation Hook
import { Callout } from "fumadocs-ui/components/callout";
The `UmiaValidationHook` is the smart contract that enforces per-step bid eligibility during a Tailored Auction. It is called by the CCA on every bid submission and decides whether the bidder is allowed to participate in the current auction step. [Bid Validation](/docs/technical-reference/bid-validation) charts every path a bid takes through it.
## Overview
Each auction can have one validation hook attached. The hook accepts two credentials, which can be mixed per step. Both travel in the bid's `hookData`: `validate()` is the only entry point, and nothing is submitted ahead of a bid.
1. **Inline zkTLS proof**: proof passed directly in the bid's `hookData`. On an ordinary step it registers the wallet for later bids.
2. **Inline server permit**: EIP-712 signed permit passed in the bid's `hookData`, verified and consumed during the bid transaction.
Verification is **monotonic**: a user verified at step N is automatically eligible for steps N, N+1, N+2, and beyond. This models tiered access where earlier tiers are supersets of later ones.
## Interface discovery (ERC165)
The hook follows [CIP-1](https://github.com/Uniswap/continuous-clearing-auction/blob/main/CIPs/cip-1.md), the CCA standard for validation hooks, so an integrator can identify it from its address alone rather than from a trusted list. Read `validationHook()` off the auction, then call `supportsInterface`:
| Interface | ID | Meaning |
| ---------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
| `IERC165` | `0x01ffc9a7` | Supports introspection |
| `IValidationHook` | `0x22c44b5f` | Is a CCA validation hook (has `validate`) |
| `IUmiaValidationHook` | `0xbff343b3` | Is this hook, with the gating reads and proof relays below |
| `IMaxBidPriceValidationHook` | `0x2268a4c3` | Exposes a bid price cap via `maxBidPrice()` (`0` = no cap) |
| `IGatedValidationHook` | `0x6d417064` | Early bidding is gated until `expirationBlock()` (`0` = never gated) |
| `IVerifyEveryBidHook` | `0x98e51cb6` | Can require a fresh credential on every bid at a step (`verifiesEveryBid`, `authorizesWithoutCredential`) |
`IUmiaValidationHook` covers the permissionless surface only: the reads that describe the gate (`cca`, `getSteps`, `isStepEnabled`, `isStepPermitEnabled`, `getStepProviders`, `isVerified`, `signer`, `stepMaxBidAmount`, `zkBidTotal`, `isPermitNonceUsed`, `identityOwner`). The owner-only admin functions are outside it, so routine admin changes never shift the ID. Removing the proof relays (`submitProof`, `submitProofBatch`) did change it; hooks deployed before still report the earlier ID.
`IMaxBidPriceValidationHook` is Uniswap's interface for a price-capped hook, and our `maxBidPrice()` matches it in both signature and meaning (`0` = no cap), so generic CCA tooling can read our cap. One difference: Uniswap's cap is immutable, ours can be changed by the hook owner, so read it fresh rather than caching it.
The cap rejects with `MaxBidPriceExceeded()`, whose selector matches Uniswap's hook, so a client that knows the standard can decode the failure without this contract's ABI.
`IGatedValidationHook` is the gating half of Uniswap's `IGatedERC1155ValidationHook`, the interface their auction UI reads to learn that early bidding is restricted: it blocks bidding while `block.number < expirationBlock()` and lifts the restriction on its own once that block passes. The ID is theirs even though we skip the ERC1155 ownership check it upstream inherits, because Solidity excludes inherited selectors when computing an interface ID. `expirationBlock()` returns the end of the last gated step, or `0` when no step gates. The hook owner can move the gate mid-auction, so read it fresh rather than caching it.
## hookData Format
When a user submits a bid, the CCA forwards a `hookData` bytes payload to `validate()`. The step's gate configuration decides which credential is required; the first-byte **type flag** only picks between them when a step has both a proof gate and a permit gate configured:
| First byte | Type | Payload (remaining bytes) |
| --------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| `0x01` | Server permit | `abi.encode(uint256 permitStep, bytes32 nonce, uint256 deadline, bytes signature)` |
| Any other value | zkTLS proof | First 32 bytes: `uint256 proofStep` (the step the proof targets), followed by `abi.encode(Reclaim.Proof)` |
A missing, wrong-kind, or truncated payload is rejected with the gate's own error (`ServerPermitRequired` / `ProofRequired`) rather than an opaque decode failure.
### Server permit inline (`0x01`)
```
hookData = 0x01 ++ abi.encode(permitStep, nonce, deadline, signature)
```
* **permitStep** (`uint256`): The 0-indexed auction step the permit was signed for. Must equal the current step on steps that verify every bid; ordinary steps accept ≤ the current step (monotonic).
* **nonce** (`bytes32`): Single-use value chosen by the signer. Burned when the permit is consumed; reuse reverts with `PermitAlreadyUsed`.
* **deadline** (`uint256`): Unix timestamp after which the permit expires.
* **signature** (`bytes`): EIP-712 signature from the authorized signer over the `ServerPermit` struct.
The hook enforces **monotonic inline verification**: `permitStep` must be ≤ the current auction step. The permit bitmap is checked against `permitStep`, and the EIP-712 signature is verified for `permitStep`. This allows a user who obtained a permit at step N to bid at a later step M that also accepts permits. On a step that takes only proofs, a permit reverts `ProofRequired`.
### zkTLS proof inline (default)
```
hookData = abi.encodePacked(uint256 proofStep) ++ abi.encode(Reclaim.Proof)
```
If the first byte is anything other than `0x01`, the hookData is treated as a step-prefixed zkTLS proof:
* **proofStep** (`uint256`, first 32 bytes): The 0-indexed auction step the proof was originally verified for.
* **proof** (remaining bytes): ABI-encoded `Reclaim.Proof`.
The hook enforces **monotonic inline verification**: `proofStep` must be ≤ the current auction step. The proof is verified against the **proofStep's** provider set, not the current step's. This allows a user who verified at step N (with provider X) to bid at step M (M ≥ N) even if step M uses different providers.
After verification, the user is registered from `proofStep`, so later ordinary steps that take proofs accept their bids without a credential.
### Empty hookData
If `hookData` is empty and the user has no pre-stored verification, the bid reverts with `NotVerified(owner)`.
On an ordinary step that takes proofs, a user registered by an earlier proof bids without a credential and the `hookData` is ignored. Standing verification is checked first. Server permits never create it.
## Server Permit System
Server permits use EIP-712 typed signatures to gate access. A trusted backend signer issues permits to eligible wallets, and the contract verifies the signature onchain.
### EIP-712 Domain
```solidity
EIP712Domain(
string name, // "UmiaValidationHook"
string version, // "1"
uint256 chainId, // Bound at deployment
address verifyingContract // Hook contract address
)
```
### Permit Struct
```solidity
ServerPermit(
address wallet, // The wallet being permitted
uint256 step, // The auction step index
bytes32 nonce, // Single-use nonce, burned on consumption
uint256 deadline // Unix timestamp expiry
)
```
### Submission Path
Permits are **inline-only**: include the permit in the bid's `hookData` with the `0x01` prefix. The permit is verified and its nonce burned during the bid transaction, and it authorizes that single bid only. Unlike zkTLS proofs, a permit does **not** register the user: every bid in a permit-gated step needs a fresh permit and nonce, because the off-chain signer is the source of truth for per-wallet bid caps.
## Step Configuration
Each step can independently be configured for zkTLS verification, server permit verification, or both.
### Bitmaps
The hook uses two bitmaps to track which steps enforce verification:
* **Step enabled bitmap** (`_stepEnabledBitmap`): Bit `i` set means step `i` requires verification of any kind (zkTLS or server permit). If a step is not enabled, any wallet can bid without verification.
* **Step permit enabled bitmap** (`_stepPermitEnabledBitmap`): Bit `i` set means step `i` accepts server-permit signatures. A server permit submitted for a step where this bit is not set will revert with `ServerPermitNotEnabled`.
### Admin Functions
All admin functions are restricted to the hook owner.
| Function | Description |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `enableStep(stepIndex, providerHashes, providerIds)` | Enable zkTLS verification for a step with specific provider requirements |
| `enableStepBatch(stepIndices, providerHashesPerStep, providerIdsPerStep)` | Batch variant of `enableStep` |
| `disableStep(stepIndex)` / `disableStepBatch(stepIndices)` | Disable verification for a step (anyone can bid) and clear its verify-every-bid flag |
| `enableStepPermit(stepIndex)` | Enable server-permit verification for a step |
| `disableStepPermit(stepIndex)` | Disable server-permit verification for a step |
| `setSigner(address)` | Set the authorized EIP-712 signer (set to `address(0)` to disable all permits) |
| `addStepProviders(stepIndices, hashes, ids)` | Add required zkTLS provider hashes to steps |
| `removeStepProviders(stepIndices, hashes)` | Remove provider hashes from steps |
| `setStepProviders(stepIndex, hashes, ids)` / `setStepProvidersBatch(...)` | Replace a step's provider set atomically |
| `setMaxBidPrice(maxBidPrice)` | Cap the max price a bid may carry (`0` disables the cap); bids above it revert `MaxBidPriceExceeded` |
| `unregister(user)` / `unregisterBatch(users)` | Clear a user's standing registration; any valid registration proof can register them again |
| `clearIdentity(providerHash, identityHash)` | Release a claimed provider-scoped identity |
| `setCCA(address)` | Pair the hook with a CCA contract (called by owner or router; effectively one-time, subsequent calls are no-ops) |
### Permit Wallet Lists
The server-side permit signing service maintains an off-chain **wallet allowlist** per auction step. When a wallet requests a permit:
* An exact allowlist row at the active permit step overrides that step's policy with the wallet's own cap.
* Otherwise, a configured default policy applies: open-to-all grants screened wallets the default cap; a whitelist-gated policy grants no permit. Earlier rows never override a configured default policy.
* Only when the active step has no default policy can the highest eligible earlier permit-step row supply the cap. Verify-every-bid steps accept only their own row. A zero cap blocks issuance.
The Hub describes eligible earlier-round entries only for rounds that do not require verification on every bid; verify-every-bid rounds use their own allowlist rows. A configured default policy still prevents earlier-row fallback.
Every wallet on an auction's allowlist shows as **Angel** next to its bids on the hub, unless an operator assigns it a label for that auction (currently **Fund**; one label per wallet, covering every step). A wallet that bid through zkTLS shows a **zkTLS** tag instead of Angel, but never instead of a label; wallets outside the allowlist that did not use zkTLS carry no tag. The operator note and the per-wallet cap never leave the admin side.
Wallet lists are managed via the Umia CLI:
```bash
# List permitted wallets
umia permit-wallets-list --auction 0x... --step 0
# Add a single wallet
umia permit-wallets-add --auction 0x... --step 0 --wallet 0xabc...
# Bulk add from file (one address per line)
umia permit-wallets-add --auction 0x... --step 0 --file wallets.txt
# Label the added wallets (--label none clears it; omit to keep the label)
umia permit-wallets-add --auction 0x... --step 0 --file funds.txt --label fund
# Replace entire list atomically
umia permit-wallets-set --auction 0x... --step 0 --file wallets.txt
# Remove a wallet
umia permit-wallets-remove --auction 0x... --step 0 --wallet 0xabc...
```
## Validation Flow
When `validate()` is called on a bid:
1. If no CCA is paired, the bid passes.
2. Require the caller to be the paired CCA. The bid sender may differ from the owner; credentials and caps bind to the owner, while the CCA collects the sender's funds.
3. If a max bid price is configured and the bid's max price exceeds it, revert with `MaxBidPriceExceeded`.
4. Resolve the current auction step from block number.
5. If the step is not enabled for verification, the bid passes. An enabled step with no credential gates also passes unless it verifies every bid, in which case it fails closed.
6. On ordinary proof-gated steps, accept pre-stored verification from a step ≤ current step, subject to zkTLS caps. Permit-only steps and steps that verify every bid ignore that status.
7. If a credential is required, decode `hookData` according to the step's gate configuration:
* Empty: revert `ServerPermitRequired`, `ProofRequired`, or `NotVerified` depending on which gates the step has.
* Permit gate (payload prefixed `0x01`, or the step is permit-only): verify and consume the server permit inline; `permitStep > currentStep` reverts `PermitStepTooHigh`.
* Proof gate otherwise: decode `proofStep` from the first 32 bytes. If `proofStep > currentStep`, revert `ProofStepTooHigh`. Verify the zkTLS proof against `proofStep`'s providers.
8. On steps that verify every bid, require `proofStep` or `permitStep` to equal the current step, and never accept such a step's proof or permit at any other step. Proof timestamps must be within the last ten minutes and cannot be in the future. The signed proof context must be `bid:::::`. The hook consumes the proof identifier; permits consume their nonce.
9. On ordinary steps, successful **proof** verification stores the step the user is verified from. Registered users bid without a credential on later ordinary steps that take proofs, so it changes only through `unregister`. A permit-only step still takes a permit from them. Bid proofs never create standing registration; neither do permits.
Enable `setVerifyEveryBid(step, true)` on steps that verify every bid after configuring their accepted credentials, in the same `multicall` batch and behind `requireStepNotStarted(step)` so the step never starts half-configured. Leave it off for early-bid steps so inline registration and later bids keep their existing flow. With both gates configured, each bid can supply either credential. Each proof request needs its own context, `bid:::::` (`bidProofContextMessage` in `@umia/types`).
Proof verification uses the beacon's witness data without consuming its public replay registry. A copied call to Reclaim `verifyProof` cannot burn the pending bid proof. Early-bid registration remains reusable for bidding within its auction. Registration is idempotent, while bid proofs remain single-use. Registration proofs require a signed `register:::` context and cannot register the same owner in another auction.
A relayer can fund and submit a bid for the credential's owner. Refunds and token claims still go to the stored owner. The permit's signed amount cannot be changed, and another address cannot be substituted as owner. Bid price remains a sender-supplied value subject to the hook's price cap. Someone copying a complete bid can still fund the full authorized amount for the same owner and consume the credential; proof-only consumption is prevented, but public-mempool ordering is not guaranteed.
These changes require a compatible hook deployed with the auction. Existing auctions have immutable hook addresses and cannot acquire this behavior from an API update.
## Events
| Event | Emitted when |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `Registered(stepIndex, user)` | User's verified step is stored (ordinary zkTLS proof paths only) |
| `Unregistered(user)` | User's standing registration is cleared |
| `SignerSet(oldSigner, newSigner)` | Permit signer is changed |
| `VerifyEveryBidSet(stepIndex, required)` | A step started or stopped verifying every bid |
| `StepPermitEnabled(stepIndex)` | Server permit enabled for a step |
| `StepPermitDisabled(stepIndex)` | Server permit disabled for a step |
| `StepEnabled(stepIndex)` | Verification enabled for a step |
| `StepDisabled(stepIndex)` | Verification disabled for a step |
| `StepProviderSet(stepIndex, providerHash, providerId)` | Provider added to or set for a step |
| `StepProviderRemoved(stepIndex, providerHash)` | Provider removed from a step |
| `ProofVerified(user, stepIndex, proofIdentifier)` | zkTLS proof verified |
| `PermitConsumed(user, stepIndex, nonce)` | Server permit verified and its nonce burned |
| `IdentityClaimed(...)` / `IdentityCleared(providerHash, identityHash)` | Provider-scoped identity claimed / released |
| `MaxBidPriceSet(maxBidPrice)` | Max bid price cap changed |
| `CCASet(cca)` | Hook paired with its CCA |
## Error Reference
| Error | Cause |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `NotVerified(user)` | Required credential is absent; steps that verify every bid ignore prior verification |
| `CredentialStepMismatch(credentialStep, currentStep)` | A credential on a step that verifies every bid targets another step |
| `BidProofExpired()` / `BidProofFromFuture()` | A bid proof is too old or future-dated |
| `BidProofContextMismatch()` | Missing or incorrect chain, auction, step, amount, or nonce in signed bid context |
| `ProofAlreadyUsed(bytes32)` | This bid proof was already consumed |
| `NoGateConfigured(stepIndex)` | A step that verifies every bid has no credential gate |
| `ProofRequired(stepIndex)` | Step has a zkTLS gate but the payload isn't a valid proof envelope |
| `ServerPermitRequired(stepIndex)` | Step has a permit gate but the payload isn't a valid permit envelope |
| `ServerPermitNotEnabled(stepIndex)` | Server permit submitted for a step that doesn't accept permits |
| `SignerNotSet()` | No signer configured (signer is `address(0)`) |
| `ExpiredDeadline()` | Permit deadline has passed |
| `InvalidSignature()` | EIP-712 signature doesn't match the configured signer |
| `PermitAlreadyUsed(nonce)` | Permit nonce was already consumed |
| `PermitStepTooHigh(permitStep, currentStep)` | Inline permit targets a future step (`permitStep > currentStep`) |
| `StepIndexOutOfBounds(stepIndex)` | Step index exceeds the auction's step count |
| `NoCCA()` | Admin call before a CCA is paired (bids simply pass in that state) |
| `ProofStepTooHigh(proofStep, currentStep)` | Inline proof targets a future step (`proofStep > currentStep`) |
| `ProviderHashMismatch(expected, actual)` | zkTLS proof provider doesn't match step requirements |
| `IdentityAlreadyClaimed(providerHash, identityHash, existingUser)` | Another wallet already claimed this provider-scoped identity |
| `MaxBidPriceExceeded()` | Bid's max price exceeds the configured cap. Selector matches Uniswap's `MaxBidPriceValidationHook` |
| `PriceNotAlignedToTick()` | Bid price not aligned to the auction's tick grid |