How the reference price increases

Two functions of ReferenceCurve_v1 increase the reference price: rebalance (rebalanceSegments) and elevation (elevate). The reference price is the lowest price on the curve. A rebalance uses collateral that the market already holds for supply bought above the reference price. An elevation adds collateral from outside the curve, such as fees that reach the market’s ElevationTreasury_v1.

Rebalance

How it works

The caller submits a complete new list of segments. The contract replaces the curve if every check below passes, in this order. The check names (B1 to B6, I3) are the ones in the contract’s comments.

1. State. The block timestamp is at or below the call’s deadline, the hash of the current segments equals the expected hash, and the virtual collateral supply equals the expected value. Otherwise the call reverts before any other check and moves no collateral.
2. Reference price (B1). The new reference price is at or above the current one.
3. Capacity (B5). The new curve’s capacity is at or above the current supply and at or below the issuance token’s cap.
4. Supplied collateral (B2). The contract pulls the supplied collateral from the caller and adds the amount received to the virtual collateral supply. That amount must equal the amount the call names. This comparison runs after the segment rules (6).
5. Reserve held (B3). The reserve for the current supply under the new segments is at or below the virtual collateral supply.
6. Segment rules. The rules in Markets and curves apply.
7. Reserve for supply (B6). The reserve for the current supply under the new segments is at or above the reserve under the old segments.
8. Spot does not fall (I3). Spot at the current supply is at or above the old spot.
9. Spot tolerance (B4). Spot rises by at most the spot tolerance (Curve shape).

The call does not change supply, and it draws no reserves. It works while trading is open, which reconfigureSegments does not. $$R_{\text{old}}(S) \le R_{\text{new}}(S) \le V + X$$ $$r_{\text{new}} \ge r_{\text{old}}, \qquad p_{\text{old}}(S) \le p_{\text{new}}(S) \le p_{\text{old}}(S) \cdot \left(1 + \frac{t}{10\,000}\right)$$ where:

• $S$ is the issuance supply
• $R_{\text{old}}(S)$ and $R_{\text{new}}(S)$ are the reserve for $S$ under the old and new segments
• $V$ is the virtual collateral supply before the call
• $X$ is the collateral supplied in the call (suppliedCollateral_)
• $r_{\text{old}}$ and $r_{\text{new}}$ are the reference prices
• $p_{\text{old}}(S)$ and $p_{\text{new}}(S)$ are spot at $S$
• $t$ is the spot tolerance in basis points

When $X$ is 0 and $V$ equals $R_{\text{old}}(S)$, the first line fixes $R_{\text{new}}(S) = V$. The new curve holds the same collateral for the same supply. A higher reference price puts more of that collateral in the reference segment, so the premium supply below spot holds that much less. Example. A curve has:

• a reference segment of 1,000 tokens at 1.00
• a band of 5 steps of 100 tokens, from 1.20 rising 0.20 per step to 2.00
• a tail of 20 steps of 100 tokens, from 2.04 rising 0.04 per step to 2.80

Supply is 2,000: the reference segment, the full band and 5 tail steps. The rebalance keeper submits a new curve with no supplied collateral:

• a reference segment of 1,500 tokens at 1.28
• 5 steps of 100 tokens, from 1.56 rising 0.16 per step to 2.20
• 15 steps of 100 tokens, from 2.24 rising 0.04 per step to 2.80

After the call:

• the reference price is 1.28, and the reference segment holds 1,920.00 of the 2,860.00 reserve
• the premium supply below spot holds 940.00, down from 1,860.00
• an address that sells 100 tokens at supply 2,000 receives 220.00 before fees, the same as before the call

The 500 tokens bought in the tail added 1,060.00 to the reserve at tail prices. After the rebalance, that collateral is part of the cost of a reference segment 500 tokens longer, at a higher reference price. The example’s new curve is chosen by hand to keep the arithmetic short. Under the keeper policy below, the new curve is the configured band and tail rebuilt from the curve policy at the new reference price and reference-segment capacity.

Re-form after the reference segment shrinks

A sell that takes supply below the reference segment’s capacity shrinks the reference segment to the supply (Markets and curves). The band and tail then start at the lower supply with their old widths. A re-form is a rebalance that keeps the reference price and rebuilds the band and tail from the curve policy at the new reference-segment capacity. Example. The curve above, before the rebalance, has supply 1,000. Sells take 200 tokens out of supply at a sell fee of 0. Before the re-form, the next buyer pays 1.20 for tokens 801 to 900. After it, the next buyer pays 1.20 for tokens 801 to 880. The band is 50% of the reference segment again, so price discovery restarts from the new end of the reference segment.

Keeper policy

The rebalance keeper decides when to call rebalanceSegments and which segments to submit. That decision is keeper policy, off chain. In the configuration code this policy is named the LRE step. The interval and the shrink share are deployment settings.

Elevation

How it works

The caller offers a collateral budget. The contract walks the premium steps upward from the reference price:

1. The reference supply $b$ is the smaller of the reference segment’s capacity and the supply.
2. The cost of the next step is its price minus the reference price, times $b$, rounded up. The tokens in that step were bought at the step’s price, so only the reference supply needs raising to it.
3. If the remaining budget covers the cost, the step joins the reference segment. The reference price becomes the step’s price, $b$ grows by the step’s width up to the supply, and the cost leaves the budget.
4. Otherwise, the rest of the budget is spread over the reference supply, and the walk stops.
5. The contract computes the reserve for the supply under the new segments. It pulls the difference between that reserve and the virtual collateral supply from the caller. The rest of the budget stays with the caller.

The walk never absorbs the last step of the last premium segment. $$c_i = \lceil (p_i - r_i)\, b_i \rceil, \qquad r_{i+1} = p_i, \qquad b_{i+1} = \min(b_i + q_i,\ S)$$ $$r' = r_n + \left\lfloor \frac{D}{b_n} \right\rfloor, \qquad X = R_{\text{new}}(S) - V$$ where:

• $p_i$ and $q_i$ are the price and width of the $i$-th premium step
• $r_i$ and $b_i$ are the reference price and reference supply before step $i$
• $c_i$ is the cost of absorbing step $i$
• $n$ is the first step the budget does not cover
• $D$ is the budget left at step $n$
• $r'$ is the new reference price
• $S$ is the issuance supply
• $V$ is the virtual collateral supply before the call
• $X$ is the collateral the contract pulls from the caller

Example. A curve has a reference segment of 1,000 tokens at 1.00 and a premium segment of 10 steps of 100 tokens, from 1.20 rising 0.20 per step. Supply is 1,300 and the virtual collateral supply is 1,000.00 + 120.00 + 140.00 + 160.00 = 1,420.00. The caller offers 300.00. After the call:

• the reference segment is 1,100 tokens at 1.290909…
• the premium segment has 9 steps, from 1.40
• spot at 1,300 is 1.60 and the next buy pays 1.80, both unchanged
• an address that sells 300 tokens at supply 1,300 receives 160.00 + 140.00 + 100 × 1.290909… = 429.09 before fees, against 420.00 before the call

If the virtual collateral supply is above the reserve for the supply, the surplus counts toward the new reserve, and the contract pulls less. The contract then emits ElevationSurplusAbsorbed.

Elevation from the elevation treasury

At launch, the curve’s elevate is granted only to the market’s ElevationTreasury_v1. The treasury holds collateral: fees routed to it by the splitter (Fees and routing) and any collateral sent to it. An elevation from the treasury takes two calls.

1. The authorizer admin calls authorizeElevation with a supply cap and a deadline. The authorization covers one elevation and replaces any pending one. A deadline of 0 or in the past reverts.
2. An ELEVATION_KEEPER calls ElevationTreasury_v1.elevate with its own supply cap and deadline. The lower of the two caps applies.

The treasury’s elevate then runs in this order:

1. It reverts if either deadline has passed, if no authorization exists, if the supply is above the cap, or if its collateral balance is below the threshold.
2. It deletes the authorization.
3. It asks the curve for the largest budget at or below its balance that elevate accepts (maxElevatable). The quote walks at most 1,000 premium steps.
4. If the quote is 0, the call ends without calling the curve and emits ElevationExecuted with 0 attempted and 0 consumed.
5. Otherwise, it approves the budget and calls the curve’s elevate. If the curve call reverts, the treasury catches the revert. The reference price does not change and the collateral stays in the treasury.
6. It resets the approval to 0 and returns the budget offered, the collateral the curve used and the balance left.

Parameters

At launch:

• the REBALANCER role has one member, the rebalance keeper (the keeper address in the market configuration), and holds rebalanceSegments only
• the curve’s elevate is granted only to ELEVATION_MODULE, whose member is the market’s ElevationTreasury_v1
• the treasury’s elevate is granted to ELEVATION_KEEPER, whose members are the elevation keeper addresses in the market configuration
• reconfigureSegments and setThreshold are granted to no role; the authorizer admin can call them

Authority lists every role.

Scenarios

Flat curve

On a flat curve every step has the reference price (Curve shape), so the reserve for supply $S$ is $r \cdot S$.

• A rebalance with no supplied collateral raises the reference price only as far as any surplus of the virtual collateral supply over $r \cdot S$ covers. Beyond that, B3 reverts.
• A rebalance that supplies collateral can raise it, up to the reserve that the new collateral covers.
• elevate reverts. No step is priced above the reference price, so there is no premium step to absorb.

Elevation reaching the supply

When the walk absorbs the step that holds the current supply, the reference segment ends at the supply. The part of that step above the supply is dropped from the curve, and the next premium step starts at the supply. Spot is then the new reference price, and the next buy pays the next step’s price.

Edge cases

• Stale rebalance. A call after its deadline, or one whose expected segments hash or virtual collateral supply differs from the curve’s, reverts before any collateral moves.
• Freeze. rebalanceSegments, elevate, ElevationTreasury_v1.elevate, authorizeElevation and setSpotToleranceBps revert while the market is frozen.
• Supplied collateral in a rebalance. If the collateral the curve receives differs from the amount the call names, B2 reverts.
• Endowed markets. With an endowment controller registered, every new curve must keep the reference price times the smaller of supply and the new reference segment’s capacity at or above the outstanding draws. While reference sells are closed, a new reference segment longer than the supply reverts. See Endowed reference segment.
• Last premium step. A budget large enough to reach the last step of the last premium segment reverts with InsufficientPremiumSteps.
• Small budgets. A budget of 0 reverts. A budget too small to raise the reference price by 1 wei reverts with CollateralTooSmall. In wei, the smallest accepted budget is the reference supply in wei divided by 10¹⁸, plus 1.
• No supply. elevate with no issuance supply reverts with NoIssuanceSupply.
• No rise. If the new reserve is at or below the virtual collateral supply, elevate reverts with NoElevation.
• Packed limits. If a new price or reference-segment capacity does not fit its packed field, elevate reverts with InitialPriceTooLarge or SupplyPerStepTooLarge.
• Rounding. The remainder rise is rounded down. The contract pulls the exact reserve difference, and the rest of the budget stays with the caller.
• Direct budget range. maxElevatable limits its quote to 1,000 premium steps. A direct call to elevate has no step limit.

Code

Keeper policy (configuration code): _{Source: house-markets/contracts at 0ebbc89a (branch integration/v12-post-qa); house-markets/middleware at 35ebfefc (main).}