# Metrological Design: the theory behind a contract that measures instead of believing

> Canonical: https://blazephoenix.xyz/learn/metrological-design
> License: CC BY 4.0 (attribution + link) · © 2026 BlazePhoenix
> Updated: 2026-08-26



Every security review of a smart contract eventually asks the same question in a hundred costumes: where does this code act on a value it did not check? BlazePhoenix organises its entire design around asking that question exactly once, structurally, everywhere — and the method has proven distinctive enough that the v2.1 whitepaper gives it a name: Metrological Design, the discipline of building a contract as an instrument. The thesis fits in one line: code that believes is attack surface; code that measures is defence.

Metrology is the science of measurement — calibration, error bounds, instrument drift. Applying it to contract engineering means something concrete: wherever a quantity can be read from chain state, the contract reads it and never accepts a substitute; wherever it cannot, the design makes dishonesty self-defeating. Three rules carry the whole method, and every load-bearing mechanism in the protocol is an application of at least one of them.

## Rule one: one morphism, evaluated at a point

The aggregator does not contain an integration per exchange. It is the evaluation of one parametrised pricing morphism at a point of the space (venue shape, chain, fee model). If venues were branches, the live venue kinds across the chains served — each with its own fee convention — would multiply into hundreds of combinations, and multiplicative combinations mean multiplicative bytecode, multiplicative audit surface, multiplicative drift. Expressed as a morphism, the same coverage is a handful of state shapes, one stateless Core, fee conventions carried in their native units, and registration tables. Bytecode grows additively: a new venue is a row, not a branch.

The rule that guards the collapse is KIND maps to SHAPE: a new venue family is data — a kind assigned to an existing pricing shape and an address-derivation mode — never a new code path that adversarial input gets to select. And the collapse has an honesty brake: there is no single universal formula. Two closed forms are evaluated exactly (constant product, concentrated liquidity), and where replicating a curve would itself be a risk, the venue is asked through the narrowest honest channel it exposes. The morphism collapses membership, never verification.

## Rule two: coordinates are measured, never believed

The axiom under the whole attack model: the contract never acts on a modelled, nominal or caller-supplied value where an on-chain measurement exists — and no permissionless datum ever chooses which code runs. Data supplied by an untrusted party (a route, a declared fee, a claimed depth, a pool id) are coordinates: places to point the instrument, which the contract then reads for itself, fail-closed. That yields a definition of attack surface the code can actually defend: the number of code paths an adversarial input can select.

Every load-bearing defence in the engine is an instance. The Router measures its own balance delta after the pull instead of trusting the nominal amount. The fee base is re-derived in-frame from the legs as they actually executed, never read from calldata. The believability band is anchored to the candidate holding the largest measured balance of the output token — truth votes with capital, not existence. The capacity clamp cuts a concentrated leg against the pool's measured holdings, not its promised liquidity. The V4 fee gate reads the live fee from the singleton's own storage and refuses to quote when the measurement cannot be exact. Discovery proves a pool exists by reading storage nobody else can write, rather than trusting any list.

One axiom applied everywhere is also a review instrument. To audit this protocol, hunt for a site that acts on a nominal value where a measurement was available. That is the whole hunt — and it is a question a reviewer can ask mechanically, file by file, which is precisely what a named discipline is for.

## Rule three: where measurement ends, monotonicity begins

Some numbers can be neither measured nor re-derived: a caller's attested floor, a declared scale, the trader's own minimum. For these the design accepts the number and shapes the function so that lying can only hurt the liar. The attested floor can only raise the enforced floor, never lower it. The fee base is a minimum, so understating a quote cannot cheapen the fee — the coverage guard charges on delivery instead. Declared scaling is capped by measured arrival, so overstating cannot route funds that never existed. And the one bound only the trader can choose — the minimum — is mandatory at every entry point.

The economic consequence is quiet and load-bearing: a monotone input needs no trust, so it can be computed off-chain, by anyone, for free, and carried in calldata. That is how the protocol moves work off-chain without moving trust off-chain — and why the Router can offer both a solving surface and a calldata surface under the same guarantees.

> equation: effMin=max(userMinOut,routeFloor,finalHopQuote·floorBps/104) — The three-way maximum the Router enforces. Caller-supplied fields appear only inside a max, so they can tighten protection and can never loosen it — monotonicity as a security primitive.

## The discipline governs the engineering, not just the artefact

An instrument is only as good as its calibration, so the same standard applies to the process around the code. Safety margins are priced from measured hazards, never from mood: an earlier planning shave insured multi-leg routes at 5 bps per leg until the drift it insured against was measured at 2 bps — the margin was retired, because a margin that outweighs its measured hazard 27 times over is not safety, it is a tax on every honest trade. External comparisons carry their error bars or they are not published: the execution benchmark pinned quotes to the exact block they were built for after an early round mis-attributed ordinary market movement to routing, and discarded a competitor API's own gas estimates outright after real execution measured one of them 148% low.

And the measuring apparatus is itself measured. The factory census deploys through the production deployment path behind an equality gate that fails the suite if harness and deployment ever drift — because a green suite that exercises different wiring than the chain runs is not evidence, it is decoration. Instruments that test the instruments: that is the part of the method most engineering cultures skip, and the part that has caught the most.

## Why it deserves a name

Pieces of this exist elsewhere under other names. Defensive programming says validate inputs; design-by-contract says state pre- and post-conditions; formal verification proves properties about the code as written. None of them makes measurement the organising principle — the systematic preference, at every seam, for a number read from live state over a number believed from any other source, with monotone shaping as the fallback where reading is impossible, and with the engineering process held to the same standard as the artefact.

Named, the discipline becomes checkable. A reviewer does not need to absorb a hundred design decisions; they need one question and a grep. Every tolerance in this article sits in public source at a named constant, every mechanism behind it ships in the deployed bytecode, and the standing instruments — the fidelity matrix, the census, the benchmark — keep re-measuring the claims after publication. That is the difference between a philosophy and a method: a method leaves instruments running.

**Verify it yourself:** git clone https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex && cd Blaze-Phoenix-Dex && grep -n 'MEDIAN_FILTER_BPS\|MIN_SPLIT_IMPROVEMENT_PPM\|LEG_FLOOR_BPS\|MAX_CONC_DRAIN_BPS' src/*.sol  # every tolerance in this article, at its defining site

Related: https://blazephoenix.xyz/learn/the-fidelity-matrix · https://blazephoenix.xyz/learn/the-factory-census · https://blazephoenix.xyz/learn/the-on-chain-engine · https://blazephoenix.xyz/learn/the-invariants · https://blazephoenix.xyz/learn/on-chain-quoting