What a share is worth

A Nacre token is a claim on two things at once, and both halves are claimed in the same redemption. The first is a pro-rata slice of the position’s liquidity. The second is a pro-rata slice of any fees the vault has harvested but not yet compounded. There is never an instant at which part of what you own is unreachable, which sounds obvious and is the thing most of the design had to work for.

The published figure is liquidity over supply. It rises when fees are compounded and it does not fall on a deposit, a redemption or a harvest.

Why it takes four calls and not two

Harvesting and compounding are separate functions — secrete and accrete — and the split is not ceremony. In Uniswap v4 a position’s fees only move when the position is modified, so collecting them is itself a modifyLiquidity call. Collecting alone changes nothing about what a share is worth: the fees move from inside the pool to inside the vault, and both were already yours. Only accrete, which turns those balances back into liquidity without minting a single share, makes the number go up.

Keeping them apart means the one call that moves the price does exactly one thing, and the test suite can assert that the other three do not.

The two ways this leaks, and what closes them

A claim on liquidity plus idle balances has two holes in it, and both are the kind that only show up when you write the numbers down.

A deposit dilutes the idle side. If shares are minted in proportion to liquidity alone, a new depositor immediately owns a slice of fees they did not earn. So seed charges them for it: alongside the liquidity, the depositor contributes their exact proportion of the vault’s idle balances, rounded up. You buy into the vault as it stands — its position and its pending fees — rather than into a flattering picture of it.

A redemption over-collects. Removing a fraction of a v4 position collects all of that position’s pending fees, not that fraction of them. Left alone, a redeemer walks off with everybody else’s. So release splits what the call harvested: the redeemer keeps their proportion, computed against the supply before their shares were burned, and the rest stays as idle for the holders who remained.

uint256 share0 = Math.mulDiv(net0, shares, supply);
uint256 share1 = Math.mulDiv(net1, shares, supply);

amount0 = principal0 + out0 + share0;
amount1 = principal1 + out1 + share1;

Rounding has a direction

Every division in the contract is one-sided on purpose. What a depositor owes is rounded up; what a redeemer receives is rounded down. The difference is dust, and dust always lands on the same side of the table.

The first deposit also burns a thousand shares to the zero address. An empty vault whose share price can be walked up by donating to it is the oldest bug in this shape of contract, and a floor is the cheapest thing that closes it.

How this is known rather than believed

The monotonicity claim is not a comment. The suite runs a randomised sequence of swaps, seeds, partial releases and harvests against the real PoolManager bytecode and asserts after every step that liquidity per share has not fallen — and separately that the vault’s own record of its liquidity still equals the singleton’s, which is what isFlush() reads.

05  the invariant, over a random sequence
  PASS  liquidity per share never falls on seed, release or harvest
  PASS  the vault ends flush with the singleton

What the number is not is a promise you end up ahead. Liquidity per share can rise while the two tokens underneath it are worth less than when you deposited. That is impermanent loss; no vault design removes it, and this one does not claim to. Orient makes the position fungible. It does not make it safe.