# 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.
# Decentralization Roadmap
import { Callout } from "fumadocs-ui/components/callout";
During its early phase, Umia keeps two supervisory capabilities over decision markets: a market opens with Umia's approval, and a security council can pause a winning proposal for a short window after it settles. Today that council is Umia alone. Umia's part in both is temporary, and both are disclosed on [Decision Markets](/docs/decision-markets) and [Security and Audits](/docs/security). This page lays out how they are removed: in what order, what takes their place, and what needs to be true before each step. It is updated whenever a stage changes.
## What Umia Can Do Today
* **Approve a market before it opens.** Anyone can draft a decision market. Opening it onchain needs a signature from Umia over its parameters and proposals; that signature is the supervision step of this phase. A market's payload executes as written if it wins, so the check is that the payload does what the proposal says, and that a thin market is not being used to push something harmful through. The signature covers the market definition only: once a market is open, Umia cannot change its parameters, its prices, or its outcome.
* **Pause execution after settlement.** Each market carries an execution delay, four hours by default and never more than twelve. During it, the security council can pause execution of the winning proposal. Today the council is Umia alone. A pause is reserved for emergencies: an exploit, a loss of funds, criminal activity. It is not for results Umia dislikes. The pause stops execution and nothing else: it cannot pick a different winner, settle a different outcome, or move funds. Lifting it requires the protocol owner, which sits behind a public timelock.
* **Set protocol parameters and upgrade shared contracts.** The protocol owner is a timelock with a two-day public delay. It sets protocol-wide parameters such as the winning threshold, fees, and the execution delay, and it upgrades the shared contracts. Nothing it does is immediate; every change is visible onchain two days before it can execute.
- Move treasury funds.
- Change a monthly allowance.
- Change which proposal won.
- Execute a proposal that did not win.
- Stop traders in losing markets from unwinding.
None of these has an admin path. The one thing that could change that is a contract upgrade, covered under Upgrade Authority below.
## Rules That Do Not Change
Supervision sits on top of rules the contracts enforce on every market. Those rules are not part of this roadmap; they apply at every stage, and they are what make opening a market safe to leave to anyone.
* **Stake from the creator.** Whoever opens a market posts the project's minimum stake in its token, locked until trading ends.
* **One market at a time.** A project runs a single active market; the next can open once the current one settles.
* **A winning margin.** A proposal executes only if its time-weighted price beats the status quo by the project's configured threshold.
* **A delay before execution.** A settled result takes effect after a fixed interval. Today that interval is what gives the security council time to act; for a project outside the council's scope, it is simply the gap between a result and its effect.
## The Stages
Each stage removes one piece of supervision and names what replaces it. The replacement is never another trusted party: approval gives way to a fee, a stake, and proposal classes; the veto gives way to a council no single party controls, and to the holders' ability to exit.
### Stage 0: Supervised
Where the protocol is today. Umia signs every market before it opens, and is the security council's only member, able to pause execution in an emergency.
Nothing is removed yet. This stage is for battle-testing the mechanism on real markets for a while, with a person reviewing every settled market before its execution window closes. Stage 1 begins once that record is long enough to trust.
### Stage 1: Teams Open Their Own Markets
A project's operator opens markets for its own project without a signature from Umia. The stake, the single-market rule, and the threshold are unchanged. Markets drafted by anyone else still need Umia's signature, and the council is untouched.
Nothing has to replace approval here. The operator is already bound by the result; what they lose is a wait. Stage 2 begins after team-opened markets have run and executed for a while without Umia needing to step in.
### Stage 2: Anyone With Stake Opens a Market
Market creation becomes permissionless: the approval signature comes out of the contracts. Approval, which was a judgment call, is replaced by rules that cost something.
* **A cost to open.** Whoever opens a market posts the stake, returned in full when the market settles, and pays a small fixed fee to the project's treasury. An honest proposal risks nothing beyond that fee; spam pays the project every time. The exact mechanism is still being designed.
* **Proposal classes.** High-impact actions (arbitrary calls from the treasury, contract upgrades, liquidation) require a larger stake, a higher winning threshold, and a longer trading window than a budget change or a document upload. Projects choose which classes are open to outside proposers.
From here, its seat on the security council is Umia's only remaining supervisory role in decision markets. Stage 3 begins once the fee and class parameters have held up against real attempts to abuse them on live markets.
### Stage 3: The Security Council Becomes Independent
The council stops being Umia alone. It becomes a group of parties with no stake in any one project's outcomes, acting by threshold.
* **Independent members.** Security firms that review the protocol, operators of other projects on Umia, and holder delegates. Umia keeps one seat among several.
* **A threshold.** A pause needs several members to agree. No single member, Umia included, can stop a market on its own.
* **Pause, never kill.** A pause blocks execution and nothing else. Lifting it takes the same threshold, and a paused market can always be superseded by a new one with the same proposal, so a result the market stands behind can be put back to the market.
Stage 4 begins once the council has acted as a group at least once, in an incident or a drill. Holders also have a backstop of their own: a liquidation market, which winds the project down and pays the treasury out to token holders pro rata. It is a market like any other and follows the rules of whatever stage it runs in. A result holders cannot live with is answered by leaving, not by a pause.
### Stage 4: The Council Becomes Optional
A project can leave the council's scope. Outside it, the execution delay stays as a fixed, published gap between a result and its effect, with nobody who can act inside it. What remains of Umia's role is the ability to upgrade the contracts, covered below.
This stage begins after a sustained record of markets executed without a pause, and after an independent review of the market and execution contracts in their final form.
## Upgrade Authority
The protocol owner, a timelock with a two-day public delay, can upgrade the shared contracts: the hub, the market core, and the treasury implementation that projects share. This is a different kind of power from approval and the council. It does not touch any single market, but an upgrade could in principle change any rule on this page, which is why every upgrade is visible onchain two days before it can execute.
Our stance is that the core contracts stay upgradeable while the protocol is still being built. Decision markets, settlement, and the treasury are still gaining features. Once the protocol reaches the version we consider final, upgradeability is removed, by an upgrade whose only effect is to remove it. Until then, the delay is the protection, and it can lengthen as the protocol matures.
Projects do not have to wait for that. **A project can opt out of upgrades to its treasury contract today through a decision market**: the market pins the treasury to an implementation the project chooses, and from then on no protocol upgrade changes it. The project takes on its maintenance, fixes included. Markets themselves still run in the shared market core, which stays upgradeable until the protocol reaches its final version.
## Why This Order
Approval goes first because it is the larger intrusion: it sits in front of every decision, while the veto sits behind the rare bad one. Within approval, teams go before outsiders because a team is already bound by the result and has the least reason to waste its own market. The council's power goes last, and its membership widens before its power shrinks, because the cost of removing it too early is a treasury that cannot be defended, while the cost of leaving it in one party's hands too long is a trusted party that should not exist.
# 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) and the [Decentralization Roadmap](/docs/decentralization-roadmap) for the stages by which it is removed.
## 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, Workflow } 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="Every path a bid takes through UmiaValidationHook, from configuration to each revert it can hit." />
} 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.
Each price milestone is tied to its price threshold by position, and those thresholds are
written once, when the grant is created. That means a price-gated grant cannot have milestones
added or removed in place: removing one would shift another award onto the wrong threshold. To
change the milestones, terminate the grant and issue a replacement that carries the new
milestones and thresholds together. Unvested tokens from the old grant fund the new one.
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) and the [Decentralization Roadmap](/docs/decentralization-roadmap)).
## Umia Extension and zkTLS Security
The [Umia Extension](/docs/zktls-extension) generates eligibility proofs in the participant's browser, using the Reclaim Protocol's zkTLS stack run by Umia. Umia's attestor relays the encrypted TLS session with the data source and signs a claim about it. The claim proves that a specific criterion was verified against a live TLS session.
What stays private: credentials and account contents never leave the participant's browser, and the attestor sees only encrypted traffic plus the values the proof reveals. Onchain, the account identifier appears only as a pseudonym, a keyed hash computed by Umia's attestor. The attestor sees the identifier before hashing it, and Umia holds the key, so today participants trust Umia not to link accounts to wallets. [Extension Privacy and Permissions](/docs/zktls-extension-privacy) covers who sees what and how we plan to remove that trust.
What is recorded: the signed claim, including that pseudonym, is checked by Umia and submitted with the bid. The validation hook records which wallet holds each pseudonymous identity onchain, so one account can back only one wallet per auction.
## 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. The order in which each capability is removed, and what replaces it, is on the [Decentralization Roadmap](/docs/decentralization-roadmap).
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).
# Extension Privacy and Permissions
import { Callout } from "fumadocs-ui/components/callout";
This page sets out what the [Umia Extension](/docs/zktls-extension) can access, what each verification reads and reveals, who can see what, and how to check that the extension you installed is the one we published. Where something rests on trusting Umia rather than on the cryptography, it says so.
## At a glance
| | |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Site access at install | None. Chrome shows no "read and change your data" warning. |
| Who can start a verification | Only [app.umia.finance](https://app.umia.finance). |
| Site access during a verification | The exact site the criterion reads, such as `github.com`, and nothing else. You approve it each time. |
| After a verification | Site access is removed automatically, whether the proof succeeded, failed or was cancelled. |
| Code from Umia's servers on that site | None. The extension runs no scripts supplied by a server. |
| What reaches Umia | The proof, plus fixed progress events. No page content, URLs or cookies. |
| What goes onchain when you bid | Your wallet, the criterion you proved, and a pseudonym for your account. |
## Site access
1. **Install.** The extension asks for no site access. It cannot read any page until you grant it.
2. **Enable on Umia.** The first time you verify, the Umia app asks you to enable the extension for `app.umia.finance` and Umia's API. This lets the Umia app start verifications. No other website can talk to the extension.
3. **Verify.** When you start a verification, Chrome asks for access to the one site the criterion reads, for example `github.com`. Never a whole domain: approving `developers.google.com` would not give access to Gmail. You can decline.
4. **Finish.** When the verification ends, for any reason, the extension removes that site's access. The next verification asks again. An update or browser restart also clears any access left over.
You can check and remove access at any time: open `chrome://extensions`, choose **Details** on Umia, and look under **Site access**.
During a verification the extension loads the page being proven in a tab, signed in as you, using your existing session on that site. Your password is never involved, and your session cookies are never sent to Umia.
## What each criterion reads
Each criterion is a recipe: the page to load, what to match on it, and what to reveal. For example:
| Criterion | What it loads | What the proof reveals |
| ------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| GitHub contributor | Your own GitHub pull request search, scoped to the project and period the auction names | That you have at least one merged pull request there, and your GitHub account ID as a pseudonym |
| GitHub maintainer | A search of your own public repositories | That you own a public repository with at least the required stars, and your GitHub account ID as a pseudonym |
| Echo investor | Your Echo portfolio page | That you have put a nonzero amount into Echo rounds, not how much, and your Echo account email as a pseudonym |
| fomo clan | Your fomo account and profile | Which of the listed clans you belong to, and your fomo account ID as a pseudonym |
| fomo hold time | Your fomo account and profile | Your average hold time, which must be above the threshold, and your fomo account ID as a pseudonym |
Umia's attestor also sees the text it checks, such as the amount in your Echo portfolio. Only the criterion and the pseudonym go onchain.
Every recipe is published in full with each extension release (see [Checking your install](#checking-your-install)). The live registry lists the digest of every recipe it can serve, at [`/api/v1/zktls-registry/providers`](https://api.mainnet.umia.finance/api/v1/zktls-registry/providers), so anyone can match what is live to what was published.
## Who can see what
| Party | What it sees |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You | Everything, in your own browser. |
| The site you verify on | A normal visit to that page by your account. |
| Umia's attestor | The site's hostname, the timing and size of the encrypted connection, and the parts of the response the proof reveals, including your account ID before it becomes a pseudonym. Never your password or session cookies. |
| Umia's API | The finished proof: your wallet, the criterion and the pseudonym. Plus the progress events above. |
| Everyone, onchain | When you bid with a proof: your wallet, the criterion and the pseudonym. |
Anyone can see which criterion a bidding wallet proved. For a narrow criterion, such as contributing to one small project in one quarter, that alone narrows down who the wallet might belong to, even though the account is only a pseudonym.
### Can Umia link your account to your wallet?
Today it could, and two things rest on trusting us not to:
1. **The attestor sees your account ID.** Pseudonyms are currently computed on the attestor (Reclaim's `oprf-raw` mode), so it receives your account ID in the clear before hashing it. We do not log or keep it, but you cannot verify that yet: the attestor does not run as a publicly verifiable build.
2. **Umia holds the pseudonym key.** A pseudonym is a keyed hash of your account ID. The attestor holds the key it uses, and a copy is kept offline for recovery. Whoever holds the key can recompute the pseudonym for a known account and find its wallet onchain. We use the offline copy only to recover the attestor.
The public can do neither: without the key, a pseudonym reveals nothing about the account behind it.
We plan to remove both assumptions:
* **Blind the account ID in your browser.** With Reclaim's client-side OPRF, the extension proves the account ID in zero knowledge and the attestor computes the pseudonym without ever seeing the ID.
* **Remove the single key holder.** Either run the attestor in a trusted execution environment with a published, reproducible build, so anyone can check the code that holds the key, or split the key with an independent operator, so no single party can compute pseudonyms alone.
## No server code runs on the sites you verify
A recipe is data: a page, patterns to match and parts to reveal. The extension refuses any recipe that carries a script, and the registry refuses to save or serve one. What the extension does on a provider's site is fixed in the published extension code, not decided by a server at verification time.
## Checking your install
Every version we publish to the Chrome Web Store is also published as an immutable release on [umiafinance/extension](https://github.com/umiafinance/extension/releases). Once a release is published, GitHub prevents its tag and files from changing. Each release contains:
* the packaged extension, with an `artifact-manifest.json` listing every file's SHA-256 and the commit it was built from;
* `zktls-recipes.json`: every committed recipe, with its digest and the claim hashes an auction pins;
* `SHA256SUMS` for the files above.
The release notes link the matching source on [umiafinance/extension](https://github.com/umiafinance/extension), which holds everything the build reads, including the SDK. Its [README](https://github.com/umiafinance/extension#readme) gives the commands to compare the extension Chrome installed with the release, and to rebuild the release yourself.
You can check that the installed extension is exactly the published build, file for file. The one exception is the toolbar icons, which the Chrome Web Store re-encodes. You can also rebuild the release from source and get the same files. This covers the extension only, not Umia's attestor or API, which run on Umia's servers.
## Audits
The extension and its SDK have not had an external audit yet. The zero-knowledge and attestation cryptography they use comes from the [Reclaim Protocol](https://docs.reclaimprotocol.org/).
## Staying safe
* Install only from the [Chrome Web Store listing](https://chromewebstore.google.com/detail/umia/ejcaahfcaaiblipldkfijdcbannidbdd). The extension ID is `ejcaahfcaaiblipldkfijdcbannidbdd`.
* Umia will never message you asking you to "verify now". Start verifications only from [app.umia.finance](https://app.umia.finance).
* If you prefer, use a separate Chrome profile signed in only to the site you verify on.
* The extension is only needed for gated rounds. You can take part in public rounds without it.
# Umia Extension and zkTLS
import { Callout } from "fumadocs-ui/components/callout";
import { ExtensionBanner } from "@/components/docs/extension-banner";
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. The public sees only that a wallet met the criterion, through a pseudonym rather than the account itself.
The Umia Extension is built on the [Reclaim Protocol](https://docs.reclaimprotocol.org/), with Umia running its own attestor and provider registry. 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 live on the Chrome Web Store. It 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 [zkTLS Integration](/docs/technical-reference/zktls-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 publish their accounts to have their eligibility checked. You can verify things users might not want publicly tied to 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 shown on the auction page, so participants know what qualifies before they verify.
## Security and Trust Assumptions
Proof generation happens in the participant's browser. An attestor operated by Umia relays the encrypted TLS session and signs the resulting claim; the participant's password and session cookies never reach Umia. The chain sees only that signed claim, which recipes keep to the minimum the criterion needs, such as a pseudonymous account identifier used to stop one account from qualifying several wallets.
The extension has no site access at install, asks for one exact site per verification, removes that access when the verification ends, and runs no code supplied by Umia's servers. Today Umia's attestor sees the account identifier before it becomes a pseudonym, so participants trust Umia not to link accounts to wallets; [Extension Privacy and Permissions](/docs/zktls-extension-privacy) sets out exactly what each party can see, how to check the extension you installed, and how we plan to remove that trust.
# 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
## SLOP venture contracts
Slop Cash launched on Umia as venture #1 on Robinhood Chain. Use these contracts when interacting with the SLOP token, its treasury, or its auction. Its spot liquidity vault and pool are created when the auction ends.
# 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: 79580c82879aa21fd0e13a4d5deaf60d661d07557b41c7c6306704f3e738e8f7 */}
{/* 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)"]
namespace["For each proof hash, setIdentityProvider(hash, namespace)
Allowed before pairing; the assignment cannot change"]
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
deploy --> namespace
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). |
| `setIdentityProvider(providerHash, identityProvider)` | Permanently assigns a claim hash to its identity namespace. |
| `clearIdentity(identityHash)` | Frees an identity slot shared across recipes in that namespace. |
| `multicall(calls)` | Runs owner calls atomically. Leading with `requireStepNotStarted(step)` makes a late-mined batch revert. |
Everything except `setSigner`, `setZkGlobalMaxBidAmount`, `setCCA`, `setIdentityProvider`, `clearIdentity` and `multicall` reverts `NoCCA` before pairing. Each proof hash needs an assigned namespace before a proof for that hash can pass. A namespace must match `^[a-z][a-z0-9_]{0,63}$` or `setIdentityProvider` reverts `InvalidIdentityProvider`; assigning the same namespace again is a no-op, and changing it reverts `IdentityProviderImmutable`.
## 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 by searching
the cached schedule for the current block"]
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?
nonempty hookData, permit gate, and either
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" --> pick
pick -- yes --> permitPath
pick -- no --> standing
standing -- yes --> caps --> allow5
standing -- no --> empty
empty -- yes --> eEmpty
empty -- no --> proofPath
`}
/>
On mixed steps, an explicit permit is checked before standing zkTLS registration. A valid permit consumes its nonce and skips zkTLS counters; an invalid permit reverts without falling back to registration. Empty hook data still uses standing registration and its zkTLS caps.
These charts describe newly deployed hooks. Existing immutable hook/auction pairs retain their original behavior, including registration taking precedence over permits on older ordinary mixed steps. The ABI and interface IDs do not identify this fix; confirm the deployed implementation before relying on it. The Hub/API lets each bid select a route; switching after registration requires a fixed hook, not only an app update.
### 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(ZkTlsVerifier.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. An identity is the assigned namespace plus the signed `extractedParameters` JSON, so recipes in the same namespace share one wallet lock.
The hook calls the verifier's read-only `validateProof` to authenticate the current epoch, claim hash and witness signatures, then receive parsed context fields. The verifier uses Solady JSON traversal with guards for encoding and unique top-level security keys. Duplicate fields (including nested decoys) revert `Duplicate context key`; nested-only fields revert `Nested context key`. Escaped JSON keys revert `Escaped context key`. Identity hashing retains the exact signed object bytes, including whitespace and escapes. Rotation invalidates pending proofs from earlier epochs, while standing registrations continue to apply on ordinary steps.
b1
b1 -- yes --> eB1
b1 -- no --> b2
b2 -- yes --> eB2
subgraph beacon ["ZkTlsVerifier.validateProof: read-only authentication and parsing"]
auth{"Claim hash matches?
Current epoch?
Witness signatures valid?"}
eAuth["Revert from ZkTlsVerifier
Stale epoch includes epoch 0"]
parse{"Valid JSON encoding and grammar?
Unique top-level security keys?
Full-width hex contextAddress and providerHash?"}
eParse["Revert from context parser, including
Invalid context hex length or ParsingFailed"]
typed["Return typed fields and exact identity object bytes
No replay state read or written"]
auth -- no --> eAuth
auth -- yes --> parse
parse -- no --> eParse
parse -- yes --> typed
end
b2 -- no --> auth
regIn --> auth
`}
/>
The parser requires `contextAddress` to contain exactly 40 hexadecimal digits and `providerHash` exactly 64, each optionally prefixed by `0x` or `0X`, and returns them as an address and a bytes32. Invalid characters, shortened values and extra digits revert instead of being coerced or truncated. After authentication, the hook applies auction policy and updates its own state. Bid timestamps are checked before the verifier call; bid replay is checked after context and identity policy. Any failure reverts the whole bid, including identity and proof-consumption writes.
and matches this chain and auction?
Bid proofs also bind step and amount"}
eBind["Revert BidProofContextMismatch
or RegistrationProofContextMismatch"]
typed --> binding
binding -- no --> eBind
subgraph shared ["Hook policy for both proof kinds"]
s2{"contextAddress matches the owner?"}
s3{"The proof's step has providers,
and providerHash is one of them?"}
s4{"Proof hash assigned to an identity namespace?"}
s5{"identityProvider matches the assigned namespace?"}
s6{"extractedParameters is a nonempty object
with only nonblank string values?"}
s7{"Identity (namespace + exact object bytes)
claimed by another wallet?"}
s8["Claim the identity for the owner on first use"]
eS2["Revert ContextAddressMismatch"]
eS3["Revert ProviderNotFound or ProviderHashMismatch"]
eS4["Revert IdentityProviderMissing"]
eS5["Revert IdentityProviderMismatch"]
eS6["Revert EmptyIdentityParameters"]
eS7["Revert IdentityAlreadyClaimed"]
s2 -- no --> eS2
s2 -- yes --> s3
s3 -- no --> eS3
s3 -- yes --> s4
s4 -- no --> eS4
s4 -- yes --> s5
s5 -- no --> eS5
s5 -- yes --> s6
s6 -- no --> eS6
s6 -- yes --> s7
s7 -- yes --> eS7
s7 -- no --> s8
end
binding -- 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"])
s8 -- "bid proof" --> b4
s8 -- "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(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
On mixed early-bid steps, the user chooses Pass/server permit or zkTLS in the Hub. The user can switch routes between bids, regardless of which was used first. With the updated validation hook, each bid spends only its selected allowance; exhausting a quota does not switch routes automatically. The permit route supplies a fresh amount-bound permit. The zkTLS route supplies a stored registration proof on its first ordinary bid and empty hook data once registered, or a fresh amount/step/nonce-bound proof for every bid when the step enables verify-every-bid.
>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 session request with contextAddress = wallet
W->>R: Prove the account, contextMessage register:... or bid:...
R-->>W: zkTLS 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(identityHash)` / `identityProvider(providerHash)` | Burned permit nonces, identity slots and immutable hash-to-namespace assignments. |
| `requireStepNotStarted(step)` | Reverts `StepAlreadyStarted` once the step has started. |
| `supportsInterface(id)` | CCA validation-hook introspection, `IUmiaValidationHook`, `IMaxBidPriceValidationHook`, `IGatedValidationHook` and `IVerifyEveryBidHook`. |
# 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.
Registration is **monotonic**: a wallet registered by a proof at step N needs no credential at N and later ordinary steps that take proofs. This models tiered access where earlier tiers are supersets of later ones. Permit-only steps and steps that verify every bid ignore registration.
## 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` | `0x5084080f` | Is this hook, with the gating reads 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. Interface changes did move it (removing the proof relays `submitProof` and `submitProofBatch`, then adding `identityOwner`), so hooks deployed before those changes report an 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(ZkTlsVerifier.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 flag is checked on `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(ZkTlsVerifier.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 `ZkTlsVerifier.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 step needs a credential, the bid reverts with `ServerPermitRequired` on a permit-only step, `ProofRequired` on a proof-only step, or `NotVerified(owner)` when the step takes both.
On an ordinary step that takes proofs, a user registered by an earlier proof can bid without a credential, subject to zkTLS caps. When the step also enables permits, explicit `0x01` hook data takes precedence: the permit must validate and its nonce is consumed without debiting zkTLS counters. Invalid permits revert without falling back to registration. Other hook data is ignored for a registered wallet. Server permits never create or change standing registration.
This routing requires a newly deployed hook/auction pair. Existing immutable pairs retain their previous behavior; older ordinary mixed-step hooks may ignore permits after registration. The fix changes no ABI or interface ID, so confirm the deployed implementation before relying on it. The Hub/API still locks the credential route after the first successful credential bid. Pass and ordinary server-permit allowances remain independent offchain ledgers.
## 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
uint128 amount // The exact bid amount, in money-token base units
)
```
### 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.
### Step gates
Each step stores one gate record with three flags and its provider list:
* **Enabled**: the step enforces verification at all. A disabled step lets any wallet bid.
* **Providers**: the zkTLS proof gate. An empty list means proofs are not accepted at that step.
* **Permit**: the step accepts server permits. A permit for a step without this flag reverts `ServerPermitNotEnabled`.
* **Verify every bid**: standing registration does not count; every bid needs an inline credential.
### Admin Functions
All admin functions are restricted to the hook owner.
| Function | Description |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enableStep(stepIndex, providerHashes, providerIds)` | Enable verification for a step and set its providers (an empty list means no proof gate) |
| `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 |
| `setVerifyEveryBid(stepIndex, required)` | Require a current-step credential on every bid. On only before the step starts and while it is enabled with a proof or permit gate; off at any time |
| `multicall(calls)` / `requireStepNotStarted(stepIndex)` | Run owner calls atomically; leading with `requireStepNotStarted` makes a late-mined batch revert |
| `setMaxBidPrice(maxBidPrice)` | Cap the max price a bid may carry (`0` disables the cap). The cap must sit on the CCA tick grid; bids above it revert `MaxBidPriceExceeded` |
| `setStepMaxBidAmount(stepIndex, amount)` | Per-wallet cumulative zkTLS bid cap at a step, in money-token base units (`0` = no cap) |
| `setZkGlobalMaxBidAmount(amount)` | Auction-wide cumulative zkTLS bid cap (`0` = no cap). Settable before pairing |
| `unregister(user)` / `unregisterBatch(users)` | Clear a user's standing registration; any valid registration proof can register them again |
| `setIdentityProvider(providerHash, identityProvider)` | Permanently assign a claim hash to its account namespace |
| `clearIdentity(identityHash)` | Release a claimed identity across recipes in that namespace |
| `setCCA(address)` | Pair the hook with its CCA and cache the step schedule (one-time; later 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 (`address[,maxBid]` 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. If the step enables permits and nonempty `hookData` starts with `0x01` (or the step is permit-only), verify and consume the permit. Check its signature, wallet, exact amount, step, deadline and nonce; `permitStep > currentStep` reverts `PermitStepTooHigh`. A valid permit passes without zkTLS accrual, even for a registered wallet; an invalid permit reverts.
7. Otherwise, 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. If a credential is required, decode `hookData`:
* Empty: revert `ServerPermitRequired`, `ProofRequired`, or `NotVerified` depending on which gates the step has.
* 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.
10. Proof bids and bids covered by standing registration then count toward the zkTLS caps: the auction-wide total always accrues (so a cap set mid-auction counts earlier volume), and the owner's per-step total accrues while that step is capped. Totals are gross; refunds are never credited back. Permit bids skip these caps because the API enforces its own cap when it signs.
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 is stateless: the verifier has no replay registry, so a copied proof cannot be burned by calling the verifier. 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(identityHash)` | Shared identity claimed / released across recipes in one namespace |
| `IdentityProviderSet(providerHash, identityProvider)` | A proof hash was assigned its identity namespace |
| `MaxBidPriceSet(maxBidPrice)` | Max bid price cap changed |
| `StepMaxBidAmountSet(stepIndex, amount)` / `ZkGlobalMaxBidAmountSet(amount)` | A zkTLS bid cap changed |
| `ZkGlobalBidAccrued(owner, amount, newTotal)` | A proof or registered bid added to the auction-wide zkTLS total |
| `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 (also `setVerifyEveryBid` on an ungated step) |
| `CallerNotCCA()` | `validate` called by anything other than the paired CCA |
| `RegistrationProofContextMismatch()` | Registration proof's signed context is not `register:::` for this chain and auction |
| `ContextAddressMismatch(expected, actual)` | The proof's `contextAddress` is not the bid owner |
| `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`) |
| `ProviderNotFound(stepIndex, providerHash)` | The proof's step has no providers, or `removeStepProviders` names one that is absent |
| `ProviderHashMismatch(expected, actual)` | zkTLS proof provider doesn't match step requirements |
| `IdentityProviderMissing(providerHash)` / `IdentityProviderMismatch(providerHash)` | The proof hash has no assigned namespace, or the signed `identityProvider` differs from it |
| `EmptyIdentityParameters()` | The signed `extractedParameters` is missing or has an empty value |
| `IdentityAlreadyClaimed(providerHash, identityHash, existingUser)` | Another wallet already claimed this identity across recipes in the namespace |
| `MaxBidPriceExceeded()` | Bid's max price exceeds the configured cap. Selector matches Uniswap's `MaxBidPriceValidationHook` |
| `PriceNotAlignedToTick()` | `setMaxBidPrice` value is below the floor or off the auction's tick grid |
| `ZkBidExceedsStepCap(...)` / `ZkBidExceedsGlobalCap(...)` | The bid would push the owner's step total or the auction-wide zkTLS total past its cap |
| `StepAlreadyStarted(stepIndex)` | `requireStepNotStarted` or `setVerifyEveryBid(…, true)` after the step began |
# 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 identity-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 six layers:
| Layer | Role |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Umia provider registry | Published provider recipes, each immutable and identified by its id, that say what to prove about an offchain account |
| Umia Extension + attestor | The extension runs the provider flow in the user's browser; Umia's attestor witnesses the TLS session and signs the claim |
| Umia app frontend | Requests proofs, stores them locally, and attaches them to bids as `hookData` |
| Umia API | Signs proof-request sessions, serves the extension's session and provider endpoints, verifies proofs off-chain, stores registration proofs, computes identity hashes, and serves eligibility |
| `UmiaValidationHook` | Verifies wallet binding, provider compatibility, monotonic eligibility, and onchain identity ownership |
| CCA | 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 protocol, while Umia is the auction-specific policy layer**. Proofs use Reclaim's claim format and Umia's modified `ZkTlsVerifier` contract, but Umia hosts the stack: the attestor, the provider registry, the session backend and the extension. 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["Umia zkTLS Verifier
Lists the attestor witnesses for each epoch"]
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,
identityKey, permit wallets, hook metadata"]
EXT["Umia Extension
Runs the provider verification flow
in the user session"]
ATT["Umia Attestor
Witnesses the TLS session
and signs the claim"]
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 -->|"fetchWitnessesForClaim"| RV
HUB -->|"eligibility + proof APIs"| API
HUB -->|"proof request / proof result"| EXT
EXT -->|"provider verification flow"| PROV
EXT -->|"session, provider config, proof"| API
EXT -->|"TLS session"| ATT
ATT -->|"proxied TLS"| 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: Signed session config with wallet context
H->>E: Start verification in extension
E->>T: Provider proof flow over a TLS session
T->>P: Proxied TLS traffic
P-->>T: Encrypted response
T-->>E: Signed claim
E->>A: Submit proof to the session
E-->>H: Proof
H->>A: POST /verify with proof (registration proofs only)
note right of A: Checks the accepted session, providerHash, wallet context, identityKey
A-->>H: verifiedFromStep or error
U->>H: Place bid
H->>C: submitBid(maxPrice, amount, owner, hookData)
C->>V: validate(maxPrice, amount, owner, sender, hookData)
note right of V: Resolve step, check context, provider and identity
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. Once the wallet is registered onchain, later bids on ordinary proof-gated steps send empty `hookData`. Steps configured with `verifyEveryBid` use a server permit while the wallet's allowance covers the bid, otherwise a fresh, amount-bound proof generated for that bid, and ignore standing registration.
## How We Integrate zkTLS 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 providers per step
Auction steps are configured with `providerHash` values, plus human-readable `providerId` labels for UI/indexing. Each accepted hash is also assigned a permanent identity namespace with `setIdentityProvider` before proofs for it can pass.
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 sees the app signing key.
Instead, the API signs a session request with Umia's own app key, names the published provider by its id, and points the request at Umia's backend. The wallet must be one of the caller's linked wallets. The API records the session for that user and returns a serialized config that carries the session, a short-lived attestor credential, and the chain and verifier epoch the proof is for. During that step, Umia binds the bidder wallet into the proof context:
```text
ReclaimProofRequest.init(appId, appSecret, providerId, { envUrl: umiaBackend })
proofRequest.setJsonContext({ contextAddress: wallet, contextMessage, identityProvider })
```
`contextMessage` names the auction: `register:::` for a registration proof, or `bid:::::` for a bid proof. The API rejects any other form for an auction.
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
The extension submits the proof to the user's session, and the API accepts it only if the attestor's signature, chain, verifier epoch and pinned provider match the session. When the app then stores a registration proof, the API re-checks it and applies Umia-specific policy checks:
* the auction must actually use a zkTLS hook;
* the requested step must be enabled and must not verify every bid;
* the proof must be a registration proof (bid proofs are never stored);
* the proof must come from the caller's accepted session for this auction and hook;
* the proof's `providerHash` and pinned provider must match one of the step's accepted providers;
* the proof's `contextAddress` is the wallet bound at request time;
* the proof is normalized to the earliest step that accepts that provider and whose registration carries to the requested step.
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 an ordinary proof-gated step, the frontend sends, in order:
* empty `hookData` if the wallet is already registered onchain;
* an in-memory freshly verified proof;
* a locally cached stored proof;
* a backend-stored proof fetched for the wallet;
* a server permit, only when the wallet holds no proof and the step accepts permits.
A permit-only step always takes a server permit. A step that verifies every bid takes a permit while the wallet's allowance covers the bid, and otherwise a fresh bid proof.
## 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(ZkTlsVerifier.Proof)
```
The validation hook then:
1. resolves the current auction step;
2. checks whether that step is gated;
3. on an ordinary proof-gated step, checks whether the wallet is already registered from this or an earlier step;
4. if not, decodes `hookData` and verifies the proof for `proofStep`;
5. on an ordinary step, registers the wallet from `proofStep` for monotonic access; on a step that verifies every bid, consumes the bid proof instead.
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 registered from step `N`, the user needs no credential at `N` and later ordinary proof-gated 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 provider recipe includes in the signed `context` and `extractedParameters` fields.
If the provider emits a pseudonymous identifier, Umia's API and the hook enforce one-wallet-per-identity without ever handling a raw username (Umia's attestor still sees it while computing the pseudonym; see [Extension Privacy and Permissions](/docs/zktls-extension-privacy)). 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 stable identity shared across approved recipes for one account provider:
```text
identityKey = keccak256(abi.encode(identityProvider, canonicalExtractedParameters))
```
Two details matter here:
* `identityProvider` is the permanent namespace assigned to the approved claim hash. Recipes for the same account provider share it;
* `canonicalExtractedParameters` is taken verbatim from the signed Reclaim context both off-chain and onchain, so both layers compute the same key byte-for-byte.
Why this is useful:
* if the provider recipe captures an OPRF-derived pseudonymous identifier, the same real-world account maps to the same stable identity across recipes 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.
The OPRF output is computed during proof generation by the attestor Umia operates, and comes back signed inside the proof context. Umia's API and the hook derive `identityKey` from that signed output and never handle the raw account value. The attestor does: recipes use Reclaim's `oprf-raw` mode, in which the attestor receives the value in the clear and hashes it with its key. See [Extension Privacy and Permissions](/docs/zktls-extension-privacy) for what that means for linkability and how we plan to move to client-side OPRF.
## Sybil Resistance
Umia enforces sybil resistance in two places.
### Off-chain gate
When the API stores a proof, it computes `identityKey` and tries to claim that identity for the current hook.
It uses:
* a transaction-level advisory lock on `(hookId, identityKey)`;
* 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[identityKey]` stores the wallet that owns that identity across approved recipes;
* 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.
Missing or empty `extractedParameters` fail verification on both paths. Recipes grouped under one namespace must emit the same stable account value and canonical JSON shape.
## Submission Modes
Umia supports two verification modes in the same hook:
| Mode | How it works | Typical use |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------ |
| Inline Reclaim proof | Bid carries `proofStep + ZkTlsVerifier.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
Registration is monotonic: if a wallet registers at step `0`, it is also valid for later ordinary proof-gated steps `1`, `2`, `3`, and so on. Permit-only steps and steps that verify every bid still ask for a credential on each bid.
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;
* identity-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).