Endowed reference segment

On an endowed market, a registered endowment controller (EndowmentController_v1) draws collateral from the reserve behind the reference segment by calling ReserveManager_v1, and sends the drawn collateral to a delegate, an address that the endowment admin sets. The reserve manager also draws collateral against issuance tokens locked in positions (Overview). Endowment draws and those draws share one limit, the draw bound. The premium segments keep trading while endowment draws are made. The endowment controller is the only address that can make endowment draws, and ReserveManager_v1 records each draw against it so that the drawn amount can be restored.

Parts of an endowed market

Part	What it is	Code
Reserve manager	The contract that draws collateral from the curve and records each draw until it is restored	`ReserveManager_v1`
Endowment controller	The contract that makes draws and sends them to the delegate	`EndowmentController_v1`
Endowment admin	The address that runs setup and operates the controller	`getEndowmentAdmin`
Delegate	The address that receives each draw. The contract names it `beneficiary`	`setBeneficiary`
Outstanding draws	Collateral drawn from the curve and not yet restored: endowment draws plus outstanding credit draws. On this page, credit draws are all draws against `ReserveManager_v1` positions, by the credit facility or the staking manager	`getTotalUnbackedReserveDrawn`, `getTotalOutstandingReserves`

A market is endowed when its ReserveManager_v1 is initialized with an endowment controller address and an endowment admin address. The two addresses must be non-zero and different. Neither address has a setter, so both are fixed for the life of the reserve manager.

Setup

Initialization opens endowment setup on both the reserve manager and the curve. While setup is open:

buy, buyFor, sell and sellTo revert.
Credit draws through the reserve manager (openPosition, lockAndDraw, draw) revert.
drawUnbackedReserves reverts.
The controller’s arm reverts.

The endowment admin then completes three steps, in this order. Each step reverts if called by any other address, and each reverts after setup is closed.

Step	Function	Requires	Effect
1	`registerEndowmentController`	No controller registered yet. Issuance supply, endowment draws and credit draws are all 0	Registers the controller address fixed at initialization. Sets the same address as the curve’s reference-sell controller (`setReferenceSellController`)
2	`activateEndowment`	A registered controller. Not already activated	Sets the activated flag
3	`finalizeEndowmentSetup`	A registered controller and the activated flag	Closes setup on the reserve manager and on the curve

Registration happens once. A second call reverts, and the curve’s reference-sell controller cannot be set a second time. Finalization cannot be undone: the reserve manager has no call that reopens setup. EndowmentController_v1.initialize runs once, while setup is open. It reverts unless the controller’s configuration matches the reserve manager and curve it names and the reserve manager lists the controller as its expected controller.

Drawing

The endowment admin sets a delegate, arms the controller, and calls draw on the controller with an amount. The controller calls drawUnbackedReserves on the reserve manager. The reserve manager checks the draw bound, adds the amount to the controller’s recorded draw, and has the curve transfer the collateral to the controller. In the same transaction, the controller sends the amount, plus any collateral it already held, to the delegate. A draw does not change the curve’s virtual collateral supply, its segments or its prices. The collateral leaves the curve, and the reserve manager records it as outstanding draws.

Draw bound

A draw succeeds when total outstanding draws after the draw are at or below the reference price times the lower of supply and the reference segment’s size:

U + L + a \le P_{\text{ref}} \cdot \min(s,\ Q_{\text{ref}})

where:

$U$ is the total of endowment draws not yet restored (getTotalUnbackedReserveDrawn), in collateral
$L$ is the total of credit draws not yet repaid (getTotalOutstandingReserves), in collateral
$a$ is the amount of this draw, in collateral
$P_{\text{ref}}$ is the reference price (getReferencePrice), in collateral per token, 18 decimals
$s$ is the issuance token’s total supply
$Q_{\text{ref}}$ is the reference segment’s size, its supply per step (getReferenceMetrics)

The right-hand side is rounded down. If the left-hand side is above it, the draw reverts. Credit draws on an endowed market (_drawAgainst) check the same bound, so endowment draws and credit draws share one limit. Example. A market has a reference segment of 1,000 tokens at a reference price of 1.00. Supply is 1,250. Earlier endowment draws total 300.00, and no credit is outstanding. The controller draws 500.00.

Step	Calculation	Result
Supply counted	min(1,250, 1,000)	1,000
Bound	1.00 × 1,000	1,000.00
Outstanding draws after the draw	300.00 + 0.00 + 500.00	800.00
Check	800.00 at or below 1,000.00	Draw succeeds
Remaining room	1,000.00 − 800.00	200.00

After the draw, a further draw of up to 200.00 succeeds, and a draw of 200.01 reverts. Example. On the same curve, supply is 400 and no draws or credit are outstanding. The bound is 1.00 × min(400, 1,000) = 400.00. A draw of 500.00 reverts, and a draw of 400.00 succeeds.

Sells into the reference segment with outstanding draws

When a sell takes supply below the reference segment’s size, the curve shrinks the reference segment to the new supply in the same transaction (Markets and curves). On an endowed market, the new reference segment must still satisfy the draw bound with

a = 0

. If outstanding draws are above the reference price times the new supply, the sell reverts. Example. A market has a reference segment of 1,000 tokens at 1.00, supply of 1,000, and endowment draws of 800.00. Buyers paid 1.00 per token with a buy fee of 0, so the curve held 1,000.00 before the draws. The sell fee is 0.

Step	Calculation	Result
Collateral on the curve	1,000.00 − 800.00	200.00
An address sells 150	supply 1,000 − 150	850
Check	800.00 at or below 1.00 × 850 = 850.00	Sell succeeds; the seller receives 150.00
Collateral on the curve	200.00 − 150.00	50.00
Another address sells 100	supply 850 − 100	750
Check	800.00 above 1.00 × 750 = 750.00	Sell reverts

At 850 supply, the largest sell that succeeds is 50 tokens, which takes supply to 800 and the curve’s collateral to 0.

The controller

The endowment admin operates the controller. Every function below reverts if called by any other address, except forwardSurplus.

Function	Caller	Requires	Effect
`setBeneficiary`	Endowment admin holding `ENDOWMENT_ADMIN_ROLE`	Controller disarmed. The address is not zero, the controller, the curve, the reserve manager, the collateral token, the issuance token, the freeze guardian or the authorizer	Sets the delegate. Setting the same address again does nothing
`arm`	Endowment admin holding `ENDOWMENT_ADMIN_ROLE`	Delegate set. Setup closed and the endowment activated. The controller’s recorded addresses match the reserve manager and curve. Market not frozen	Arms the controller
`disarm`	Endowment admin	—	Disarms the controller. Works while the market is frozen
`draw`	Endowment admin holding `ENDOWMENT_ADMIN_ROLE`	Delegate set. Controller armed. Amount above 0. The same readiness and freeze checks as `arm`	Draws the amount through `drawUnbackedReserves` and sends it, plus any collateral already on the controller, to the delegate
`forwardSurplus`	Any address	Delegate set. Market not frozen	Sends any collateral on the controller to the delegate. Does nothing if the balance is 0

The delegate is settable. To change it, the endowment admin disarms the controller, calls setBeneficiary, and arms it again. The delegate starts unset: initialize reverts if the configuration names one.

Configuration fields not active in this version

ControllerConfig holds the addresses of the curve, reserve manager, collateral token, issuance token, freeze guardian and authorizer. It also has the fields pool, tracker, feeRecipient, excessTarget, forcedSaleExecutor, activationReserve, secondaryBps, minSync and feeBps. These fields are not active in this version. initialize reverts unless each of them is zero, and _isFullModeEnabled returns false.

Reference-sell switch

The curve has a reference-sell switch (setReferenceSellsClosed). Only the registered controller can call it, and the authorizer grants permission for this function only to ENDOWMENT_CONTROLLER_ROLE. The switch starts open. While the switch is closed:

sell and sellTo revert. The check covers every sell to the curve, including sells that stay within the premium segments.
buy and buyFor work.
Endowment draws and credit draws work, within the draw bound.
A new curve from rebalanceSegments, elevate or reconfigureSegments reverts if it lowers the reference price or sets the reference segment’s size above supply.

Closing the switch has no outstanding-draws condition. Opening it reverts while outstanding draws,

U + L

, are above 0. A call that sets the switch to its existing state does nothing. EndowmentController_v1 in this version has no function that calls setReferenceSellsClosed. The switch therefore stays open, and sells to the curve follow the rules in Markets and curves and the draw bound above.

Restoration

restoreUnbackedReserves returns drawn collateral to the curve. The caller approves the reserve manager for the amount. The reserve manager takes the collateral from the caller, passes it to the curve, and lowers the caller’s recorded draw and the total

U

by the same amount.

r = \min(a,\ d)

where:

$r$ is the amount restored, in collateral
$a$ is the amount the caller requests
$d$ is the caller’s recorded draw (getUnbackedDrawnBy)

The cap applies per address. A caller cannot lower another address’s recorded draw. A restore lowers

U

, which adds the same amount of room under the draw bound. Example. An address has a recorded draw of 800.00 and requests a restore of 1,000.00.

Step	Calculation	Result
Restored	min(1,000.00, 800.00)	800.00
Recorded draw after	800.00 − 800.00	0.00
Collateral taken from the caller		800.00

The only address with a recorded endowment draw is the controller. EndowmentController_v1 in this version has no function that calls restoreUnbackedReserves.

Parameters

Parameter	Unit	Set by	Setter	Bounds	Changeable after launch
Endowed option	—	Deployer, in the reserve manager’s initialization data	`ReserveManager_v1.init`	Requires a controller address and an admin address	No
Endowment controller	address	Deployer, in the reserve manager’s initialization data	`ReserveManager_v1.init`; registered by `registerEndowmentController`	Non-zero; not the admin	No
Endowment admin	address	Deployer, in the reserve manager’s initialization data	`ReserveManager_v1.init`	Non-zero; not the controller	No
Delegate	address	Endowment admin holding `ENDOWMENT_ADMIN_ROLE`	`setBeneficiary`	Controller disarmed; excluded addresses listed above	Yes
Armed	switch	Endowment admin	`arm`, `disarm`	`arm` requires setup closed and the market not frozen	Yes
Reference sells closed	switch	Endowment controller holding `ENDOWMENT_CONTROLLER_ROLE`	`setReferenceSellsClosed`	Opening requires outstanding draws of 0	No call to it in this version of the controller
Draw amount	collateral	Endowment admin, per call	`draw`	Draw bound above	—

Authority lists every role.

Scenarios

Situation	What the code does
Setup open	Buys, sells, credit draws, endowment draws and `arm` revert
Setup closed, controller disarmed	Trading works. `draw` reverts
Controller armed, draw within the bound	The draw goes to the delegate in the same transaction
Draw above the bound	The draw reverts. Nothing is transferred
Sell into the reference segment that leaves outstanding draws above the reference price times the new supply	The sell reverts
Sell that leaves supply at or above the reference segment’s size	The sell follows the rules in Markets and curves; the draw bound is not checked
Delegate change	The admin disarms, calls `setBeneficiary`, and arms again
Market frozen	`arm`, `draw` and `forwardSurplus` revert. `disarm` and `setBeneficiary` work

Edge cases

Registration with prior exposure. registerEndowmentController reverts if any issuance supply, endowment draw or credit draw exists.
Unbacked-draw flag and ceiling. The reserve manager’s unbacked-draw flag (isUnbackedDrawsAllowed) and ceiling (getUnbackedDrawCeilingBps) are set at initialization and limit drawUnbackedReserves when the reserve manager is initialized with no endowment controller. With the flag off, every call reverts. With the flag on, total outstanding unbacked draws must stay at or below the ceiling, in basis points of the lower of the virtual collateral supply and the recorded ceiling base. On an endowed market, drawUnbackedReserves checks neither the flag nor the ceiling: only the registered endowment controller can draw, and the draw bound is the only limit on the amount.
Supply below the reference segment’s size. The bound uses supply, not the reference segment’s size.
New curves. rebalanceSegments, elevate and reconfigureSegments revert if outstanding draws are above the new reference price times the lower of supply and the new reference segment’s size.
Restore with no recorded draw. restoreUnbackedReserves from an address with no recorded draw returns without a transfer and emits no event.
Collateral sent to the controller. Collateral on the controller goes to the delegate on the next draw or forwardSurplus.
Last token sold. While outstanding draws exist, a sell that takes supply to 0 reverts.

Code

Function	File
Position capacity, locked issuance times the reference price	ReserveManager_v1.sol#L35-L40
`drawReserves` (reserve manager only)	BC_Discrete_Redeeming_VirtualSupply_v1.sol#L422-L440
`registerEndowmentController`	ReserveManager_v1.sol#L315-L338
`activateEndowment`	ReserveManager_v1.sol#L340-L356
`finalizeEndowmentSetup`	ReserveManager_v1.sol#L358-L374
`drawUnbackedReserves`	ReserveManager_v1.sol#L669-L724
`restoreUnbackedReserves`	ReserveManager_v1.sol#L727-L758
`_drawAgainst` (credit draws)	ReserveManager_v1.sol#L908-L929
`_initUnbackedDrawPolicy` (endowed initialization)	ReserveManager_v1.sol#L976-L1056
`_requireEndowmentHeadroom`, `_requireEndowmentReadyIfConfigured`	ReserveManager_v1.sol#L1058-L1081
`setEndowmentSetupOpen`, `setReferenceSellController`, `setReferenceSellsClosed`	ReferenceCurve_v1.sol#L163-L217
`_buyWithEndowmentGate`, `_requireEndowmentSellOpen`	ReferenceCurve_v1.sol#L246-L266
`_combinedReserveDebt`	ReferenceCurve_v1.sol#L276-L280
`_executeSell`	ReferenceCurve_v1.sol#L421-L436
`_setSegments` (endowment checks)	ReferenceCurve_v1.sol#L856-L910
`_settleSell`, `_adjustReferenceToSupply`	ReferenceCurve_v1.sol#L1009-L1059
`drawReserves`, `restoreReserves`	BC_Discrete_Redeeming_VirtualSupply_v1.sol#L427-L460
`initialize`	EndowmentController_v1.sol#L82-L100
`setBeneficiary`	EndowmentController_v1.sol#L120-L147
`arm`, `disarm`	EndowmentController_v1.sol#L149-L184
`draw`, `forwardSurplus`	EndowmentController_v1.sol#L186-L239
`_requireDrawPermission`	EndowmentController_v1.sol#L247-L266
`_validateMembers` (inactive fields)	EndowmentController_v1.sol#L268-L321
`_validateBindings`, `_coreReady`	EndowmentController_v1.sol#L323-L365
`_isFullModeEnabled`	EndowmentController_v1.sol#L415-L417
Endowment role checks	AUT_Roles_v2.sol#L748-L780

_{Source: house-markets/contracts at 0ebbc89a (branch integration/v12-post-qa).}

Overview

How it works

Deployments

Reference