Curve shape

The curve shape is the layout of the premium segments that a ReferenceCurve_v1 market holds above its reference segment. The shape sets how much the price changes per token of supply and how far spot can sit above the reference price.

Segment layout

The contract accepts any list of segments that meets the segment rules (Markets and curves):

• 2 to 10 segments in total, the reference segment first.
• Each segment is either one step at one price, or two or more steps with a price increase above 0 at each step.
• No segment has both an initial price of 0 and a price increase of 0.
• Each segment’s initial price is at or above the price of the previous segment’s last step.
• Total capacity is at least the current supply.

Within these rules, a premium segment can hold a level run of tokens at one price or a run of steps that rise in equal increments, and the price never decreases as supply grows. The contract stores the segments only, not the parameters that produced them. rebalanceSegments and reconfigureSegments replace the segments (How the reference price increases). Example. A curve has three segments: Premium 1’s last step is priced 1.20 + 3 × 0.20 = 1.80, and Premium 2 starts at 1.80, so the list meets the price rule. A Premium 2 starting at 1.70 reverts.

Configured layouts

The curve policy in the configuration code produces one of two layouts:

Flat

On a flat curve, every step has the reference price. Every buy pays the reference price per token and every sell receives it, before fees. The configuration code builds the layout from a reference price, a reference-segment capacity and a further capacity at the same price, and rejects a flat policy with a rising tail. $$p(s) = r, \qquad R(s) = r \cdot s$$ where:

• $p(s)$ is the price at supply $s$
• $r$ is the reference price (getReferencePrice)
• $R(s)$ is the cost of supply $s$, which is the reserve the curve holds for it

Example. A flat curve has a reference segment of 1,000 tokens at 1.00 and a second segment of 9,000 tokens at 1.00. Supply is 1,000, the buy fee is 0, and a buyer deposits 300.00 collateral. No collateral sits above the reference price on a flat curve. A rebalance raises the reference price only with collateral supplied in the call or a surplus of the virtual collateral supply over $r \cdot s$, and elevate reverts. How the reference price increases covers both functions.

Bounded

A bounded curve has three parts:

1. Reference segment. $b$ tokens at the reference price $r$.
2. Band. The next $w \cdot b$ tokens. The price rises along an S-shaped path from $r$ at the band’s start to $M \cdot r$ at the band’s end. $M$ is the target multiple: spot divided by the reference price at the band’s top. $w$ is the band width, a share of the reference segment’s capacity.
3. Tail. The next $T \cdot w \cdot b$ tokens, where $T$ is the tail length in band widths. The price rises in a straight line from $M \cdot r$. The tail’s slope is set in proportion to the band and is lower than the band’s average slope.

Band, for supply $s$ from $b$ to $b(1 + w)$: $$p(s) = r + (M - 1)\, r\, f(x), \qquad x = \frac{s - b}{w\, b}$$ $$f(x) = \frac{\sigma(k(x - m)) - \sigma(-k m)}{\sigma(k(1 - m)) - \sigma(-k m)}, \qquad \sigma(z) = \frac{1}{1 + e^{-z}}$$ Tail, for supply $s$ from $b(1 + w)$ to $b(1 + w + T w)$: $$p(s) = M r + (M - 1)\, r\, g \cdot \frac{s - b(1 + w)}{w\, b}$$ where:

• $r$ is the reference price (getReferencePrice)
• $b$ is the reference segment’s capacity, in issuance tokens
• $M$ is the target multiple (config targetRatioBps ÷ 10,000)
• $w$ is the band width as a share of $b$ (config bandSupplyShareBps ÷ 10,000)
• $x$ is the position in the band, in band widths
• $f(x)$ is the band’s S-shape, 0 at the band’s start and 1 at its end
• $k = 4$ and $m = 0.35$ are the S-shape’s steepness and midpoint (STANDARD_MARKET_CURVE.shape)
• $g = 0.1705$ is the slope of $f$ at 1.2 band widths (tail.slopeSampledAt), rounded down to 1,705 bps
• $T = 100$ is the tail length in band widths (tail.bands)

Over one band width of supply, the band rises $(M - 1)\, r$ in total and the tail rises $0.1705\,(M - 1)\, r$. The tail’s total rise is $T \cdot g \cdot (M - 1)\, r = 17.05\,(M - 1)\, r$. The highest price on the curve is the price at the tail’s end, $M r + 17.05\,(M - 1)\, r$. The configuration code packs these prices into steps:

• at most 10 segments, the contract’s limit
• each price step at most a set share of $r$ (priceStepBps, set per market)
• each step price within 2% of the band’s rise $(M - 1)\, r$ from the formula (errorOfLiftBps = 200)

Example. A bounded curve has $r$ = 1.00, $b$ = 1,000 tokens, $M$ = 2.0 and $w$ = 25%. A buy past the tail’s end mints up to the curve’s capacity and refunds the rest (Markets and curves). Spot therefore sits at most 19.05 on this curve, 19.05 times the reference price. Buys above the band’s top pay tail prices into the reserve. A rebalance can move that collateral into the reference segment (How the reference price increases).

Spot tolerance

The spot tolerance is the largest rise in spot, in basis points, that one call to rebalanceSegments can cause at the current supply. A rebalance also reverts if spot at the current supply decreases. $$(p_{\text{new}}(S) - p_{\text{old}}(S)) \cdot 10\,000 \le p_{\text{old}}(S) \cdot t$$ where:

• $S$ is the issuance supply, which a rebalance does not change
• $p_{\text{old}}(S)$ and $p_{\text{new}}(S)$ are spot at $S$ before and after the call
• $t$ is the spot tolerance in basis points (getSpotToleranceBps)

Example. Spot is 2.00 and the tolerance is 500 bps (5%). The configuration code computes, for each curve, the largest gap between adjacent step prices as a share of the lower price (requiredSpotToleranceBps).

Parameters

At launch the rebalance keeper (REBALANCER) holds rebalanceSegments through that role. The rebalance keeper does not hold setSpotToleranceBps. A permission grant for setSpotToleranceBps to any role other than the authorizer admin has no effect. Authority lists every role.

Scenarios

Narrow band and wide band

Two bounded curves have the same reference segment, 1,000 tokens at 1.00, and the same reserve of 1,000.00 at supply 1,000. Both have $M$ = 2.0. The narrow band is 10% wide (100 tokens) and the wide band is 50% wide (500 tokens). Both bands are shown as five equal steps, 1.20 to 2.00, to keep the arithmetic visible. A buyer deposits 120.00 collateral at supply 1,000 with a buy fee of 0. The same deposit moves the narrow band’s price from 1.00 to 1.80 and the wide band’s price from 1.00 to 1.20. Both bands top out at 2.00. The wide band takes five times the collateral to fill, and its tail spreads the same rise over five times the supply.

Supply sold into the reference segment

A bounded curve has $r$ = 1.00, $b$ = 1,000 tokens and a band 25% wide (250 tokens). Supply is 1,000, and sells take 200 tokens out of supply. The sells shrink the reference segment in the same transaction. The band and tail keep their prices and step sizes and start at the lower supply, so the next buyer pays the band’s first step for token 801. A re-form, a call to rebalanceSegments that keeps the reference price, rebuilds the band and tail from the curve policy at the new capacity of 800 tokens. Price discovery then restarts from the new end of the reference segment. How the reference price increases shows the checks on that call.

Edge cases

• Shape values are not stored on chain. The contract checks the segment rules and the rebalance checks, not $M$, $w$ or the tail. A change to any of them takes effect only through new segments.
• Spot tolerance at 0. With the default tolerance of 0, a rebalance that raises spot at the current supply by any amount reverts.
• Spot tolerance setter. setSpotToleranceBps reverts above 10,000, for any caller without DEFAULT_ADMIN_ROLE, and while the market is frozen. Changing the tolerance does not move the curve.
• Capacity. A buy cannot go past the last step. The price at the tail’s end is the highest spot on a bounded curve, and the reference price is the only price on a flat curve.
• Flat curve and elevation. elevate on a flat curve reverts. No step is priced above the reference price, so there is no premium step to absorb.

Code

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