Validation Hook

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 charts every path a bid takes through it.

Overview

Each auction can have one validation hook attached. The hook accepts two credentials, which can be mixed per step. Both travel in the bid's hookData: validate() is the only entry point, and nothing is submitted ahead of a bid.

1. Inline zkTLS proof: proof passed directly in the bid's hookData. On an ordinary step it registers the wallet for later bids.
2. Inline server permit: EIP-712 signed permit passed in the bid's hookData, verified and consumed during the bid transaction.

Verification is monotonic: a user verified at step N is automatically eligible for steps N, N+1, N+2, and beyond. This models tiered access where earlier tiers are supersets of later ones.

Interface discovery (ERC165)

The hook follows CIP-1, 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:

IUmiaValidationHook covers the permissionless surface only: the reads that describe the gate (cca, getSteps, isStepEnabled, isStepPermitEnabled, getStepProviders, isVerified, signer, stepMaxBidAmount, zkBidTotal, isPermitNonceUsed, identityOwner). The owner-only admin functions are outside it, so routine admin changes never shift the ID. Removing the proof relays (submitProof, submitProofBatch) did change it; hooks deployed before still report the earlier ID.

IMaxBidPriceValidationHook is Uniswap's interface for a price-capped hook, and our maxBidPrice() matches it in both signature and meaning (0 = no cap), so generic CCA tooling can read our cap. One difference: Uniswap's cap is immutable, ours can be changed by the hook owner, so read it fresh rather than caching it.

The cap rejects with MaxBidPriceExceeded(), whose selector matches Uniswap's hook, so a client that knows the standard can decode the failure without this contract's ABI.

IGatedValidationHook is the gating half of Uniswap's IGatedERC1155ValidationHook, the interface their auction UI reads to learn that early bidding is restricted: it blocks bidding while block.number < expirationBlock() and lifts the restriction on its own once that block passes. The ID is theirs even though we skip the ERC1155 ownership check it upstream inherits, because Solidity excludes inherited selectors when computing an interface ID. expirationBlock() returns the end of the last gated step, or 0 when no step gates. The hook owner can move the gate mid-auction, so read it fresh rather than caching it.

hookData Format

When a user submits a bid, the CCA forwards a hookData bytes payload to validate(). The step's gate configuration decides which credential is required; the first-byte type flag only picks between them when a step has both a proof gate and a permit gate configured:

A missing, wrong-kind, or truncated payload is rejected with the gate's own error (ServerPermitRequired / ProofRequired) rather than an opaque decode failure.

Server permit inline (0x01)

hookData = 0x01 ++ abi.encode(permitStep, nonce, deadline, signature)

• permitStep (uint256): The 0-indexed auction step the permit was signed for. Must equal the current step on steps that verify every bid; ordinary steps accept ≤ the current step (monotonic).
• nonce (bytes32): Single-use value chosen by the signer. Burned when the permit is consumed; reuse reverts with PermitAlreadyUsed.
• deadline (uint256): Unix timestamp after which the permit expires.
• signature (bytes): EIP-712 signature from the authorized signer over the ServerPermit struct.

The hook enforces monotonic inline verification: permitStep must be ≤ the current auction step. The permit bitmap is checked against permitStep, and the EIP-712 signature is verified for permitStep. This allows a user who obtained a permit at step N to bid at a later step M that also accepts permits. On a step that takes only proofs, a permit reverts ProofRequired.

zkTLS proof inline (default)

hookData = abi.encodePacked(uint256 proofStep) ++ abi.encode(Reclaim.Proof)

If the first byte is anything other than 0x01, the hookData is treated as a step-prefixed zkTLS proof:

• proofStep (uint256, first 32 bytes): The 0-indexed auction step the proof was originally verified for.
• proof (remaining bytes): ABI-encoded Reclaim.Proof.

The hook enforces monotonic inline verification: proofStep must be ≤ the current auction step. The proof is verified against the proofStep's provider set, not the current step's. This allows a user who verified at step N (with provider X) to bid at step M (M ≥ N) even if step M uses different providers.

After verification, the user is registered from proofStep, so later ordinary steps that take proofs accept their bids without a credential.

Empty hookData

If hookData is empty and the user has no pre-stored verification, the bid reverts with NotVerified(owner).

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

EIP712Domain(
  string name,       // "UmiaValidationHook"
  string version,    // "1"
  uint256 chainId,   // Bound at deployment
  address verifyingContract // Hook contract address
)

Permit Struct

ServerPermit(
  address wallet,    // The wallet being permitted
  uint256 step,      // The auction step index
  bytes32 nonce,     // Single-use nonce, burned on consumption
  uint256 deadline   // Unix timestamp expiry
)

Submission Path

Permits are inline-only: include the permit in the bid's hookData with the 0x01 prefix. The permit is verified and its nonce burned during the bid transaction, and it authorizes that single bid only. Unlike zkTLS proofs, a permit does not register the user: every bid in a permit-gated step needs a fresh permit and nonce, because the off-chain signer is the source of truth for per-wallet bid caps.

Step Configuration

Each step can independently be configured for zkTLS verification, server permit verification, or both.

Bitmaps

The hook uses two bitmaps to track which steps enforce verification:

• Step enabled bitmap (_stepEnabledBitmap): Bit i set means step i requires verification of any kind (zkTLS or server permit). If a step is not enabled, any wallet can bid without verification.
• Step permit enabled bitmap (_stepPermitEnabledBitmap): Bit i set means step i accepts server-permit signatures. A server permit submitted for a step where this bit is not set will revert with ServerPermitNotEnabled.

Admin Functions

All admin functions are restricted to the hook owner.

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:

# List permitted wallets
umia permit-wallets-list --auction 0x... --step 0

# Add a single wallet
umia permit-wallets-add --auction 0x... --step 0 --wallet 0xabc...

# Bulk add from file (one address per line)
umia permit-wallets-add --auction 0x... --step 0 --file wallets.txt

# Label the added wallets (--label none clears it; omit to keep the label)
umia permit-wallets-add --auction 0x... --step 0 --file funds.txt --label fund

# Replace entire list atomically
umia permit-wallets-set --auction 0x... --step 0 --file wallets.txt

# Remove a wallet
umia permit-wallets-remove --auction 0x... --step 0 --wallet 0xabc...

Validation Flow

When validate() is called on a bid:

1. If no CCA is paired, the bid passes.
2. Require the caller to be the paired CCA. The bid sender may differ from the owner; credentials and caps bind to the owner, while the CCA collects the sender's funds.
3. If a max bid price is configured and the bid's max price exceeds it, revert with MaxBidPriceExceeded.
4. Resolve the current auction step from block number.
5. If the step is not enabled for verification, the bid passes. An enabled step with no credential gates also passes unless it verifies every bid, in which case it fails closed.
6. On ordinary proof-gated steps, accept pre-stored verification from a step ≤ current step, subject to zkTLS caps. Permit-only steps and steps that verify every bid ignore that status.
7. If a credential is required, decode hookData according to the step's gate configuration:
   • Empty: revert ServerPermitRequired, ProofRequired, or NotVerified depending on which gates the step has.
   • Permit gate (payload prefixed 0x01, or the step is permit-only): verify and consume the server permit inline; permitStep > currentStep reverts PermitStepTooHigh.
   • Proof gate otherwise: decode proofStep from the first 32 bytes. If proofStep > currentStep, revert ProofStepTooHigh. Verify the zkTLS proof against proofStep's providers.
8. On steps that verify every bid, require proofStep or permitStep to equal the current step, and never accept such a step's proof or permit at any other step. Proof timestamps must be within the last ten minutes and cannot be in the future. The signed proof context must be bid:<chain>:<lowercase auction>:<step>:<amount in base units>:<nonempty nonce>. The hook consumes the proof identifier; permits consume their nonce.
9. On ordinary steps, successful proof verification stores the step the user is verified from. Registered users bid without a credential on later ordinary steps that take proofs, so it changes only through unregister. A permit-only step still takes a permit from them. Bid proofs never create standing registration; neither do permits.

Enable setVerifyEveryBid(step, true) on steps that verify every bid after configuring their accepted credentials, in the same multicall batch and behind requireStepNotStarted(step) so the step never starts half-configured. Leave it off for early-bid steps so inline registration and later bids keep their existing flow. With both gates configured, each bid can supply either credential. Each proof request needs its own context, bid:<chain>:<lowercase auction>:<step>:<amount in base units>:<nonce> (bidProofContextMessage in @umia/types).

Proof verification uses the beacon's witness data without consuming its public replay registry. A copied call to Reclaim verifyProof cannot burn the pending bid proof. Early-bid registration remains reusable for bidding within its auction. Registration is idempotent, while bid proofs remain single-use. Registration proofs require a signed register:<chain>:<lowercase auction>:<nonempty nonce> 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

Error Reference