Connected markets

A connected market is a ReferenceCurve_v1 market whose collateral token is the issuance token of another House market, the base market. The periphery routers (AtomicBuyRouter_v1, AtomicSellRouter_v1, AtomicLoopRouter_v1 and AtomicRepayRouter_v1) trade on both markets in one transaction. The connected market’s reserve is a balance of the base market’s token, so its prices, fees and loans are all in that token. An address with the base market’s collateral token can buy, sell, loop or repay on the connected market in one router call, with no separate transaction to buy or sell the base market’s token.

Parts of a connected pair

Part	What it is	Router code name
Base collateral token (C)	The collateral token of the base market	`usdc`
Base market	A market that issues token A against C	`knxCurve`
Base token (A)	The base market’s issuance token, and the connected market’s collateral token	`knx`
Connected market	A market that issues token B against A	`knicksCurve`
Connected token (B)	The connected market’s issuance token	`nyk`
Credit facility	The connected market’s `CreditFacility_v1`, which lends A against locked B	`facility`

The sell, loop and repay routers fix one base market, connected market and credit facility at deployment. The router code names in the table are the names of those fixed addresses in AtomicRouterBase_v1.

How a connected market works

Each market is an ordinary market as described in Markets and curves. The connection is only the choice of collateral token.

The connected market’s reserve is a balance of A.
Its reference price and every step price are in A per B.
Its buy fee and sell fee are taken in A and go to its fee treasury.
Its credit facility values locked B at the connected market’s reference price in A, and lends A from the connected market’s reserve (Credit and looping).
The connected market’s curve and credit facility read prices only from the connected market’s own segments.
A buy or sell on the connected market moves existing A between the trader and the connected market’s reserve. The base market’s supply and price do not change unless the route also trades on the base market.

A route from C to B is two buys, each with its own fee:

R_A(s_A + n_A) - R_A(s_A) = D - \text{fee}_A, \qquad R_B(s_B + n_B) - R_B(s_B) = n_A - \text{fee}_B

where:

$D$ is the deposit, in C
$\text{fee}_A = D \cdot f_A / 10\,000$ , with $f_A$ the base market’s buy fee in basis points
$n_A$ is the A minted by the base market, which becomes the deposit on the connected market
$\text{fee}_B = n_A \cdot f_B / 10\,000$ , with $f_B$ the connected market’s buy fee in basis points
$n_B$ is the B minted by the connected market
$R_A$ , $R_B$ are each market’s cost of supply, and $s_A$ , $s_B$ each market’s supply before the route (Cost of supply)

Example. A buyer sends 1,000 C through AtomicBuyRouter_v1 with a minimum of 890 A from the first buy and 420 B from the second.

The base market’s buy fee is 100 bps (1%), and the buy falls within one step priced at 1.10 C per A.
The connected market’s buy fee is 100 bps (1%). Its supply sits in a step priced at 2.00 A per B with 300 tokens left, and the next step is priced at 2.40.

Step	Calculation	Result
Base market fee	1,000 × 100 / 10,000	10.00 C
Net deposit on the base market	1,000 − 10.00	990.00 C
A minted	990.00 / 1.10	900.00 A
First minimum	900.00 at or above 890	passes
Connected market fee	900.00 × 100 / 10,000	9.00 A
Net deposit on the connected market	900.00 − 9.00	891.00 A
Step at 2.00	300 tokens × 2.00 = 600.00	291.00 A left
Step at 2.40	291.00 / 2.40	121.25 tokens
B minted to the receiver	300 + 121.25	421.25 B
Second minimum	421.25 at or above 420	passes

After the route:

the base market’s reserve holds 990.00 more C, and A’s supply is 900.00 higher
the connected market’s reserve holds 891.00 more A, and B’s supply is 421.25 higher
the base market’s fee treasury holds 10.00 C, and the connected market’s fee treasury holds 9.00 A
the router holds nothing from the call, so there is no refund

Routers

Router	Markets	What one call does
`AtomicBuyRouter_v1`	Any two markets, given per call	Buys A with C, then buys B with that A
`AtomicSellRouter_v1`	The fixed pair	Sells B for A, then sells that A for C
`AtomicLoopRouter_v1`	The fixed pair and facility	Buys A with C, loops on the connected market, then sells or reinvests the A left over
`AtomicRepayRouter_v1`	The fixed pair and facility	Buys A with C, repays a loan, sells the A left over, and can sell the released B

Shared checks

Errors from these checks are prefixed Module__AtomicRouterBase__. Errors specific to the repay router are prefixed Module__AtomicRepayRouter__. The sell, loop and repay routers inherit AtomicRouterBase_v1. At deployment it requires that:

the base market, connected market and credit facility are contracts
C, A and B are three different contracts
the connected market’s collateral token is A, and the credit facility belongs to the connected market

On every call:

The receiver cannot be the zero address, the router, either market or the facility.
The input amount must be above 0.
The call reverts if the deadline is before the current block time. A call at the deadline runs.
Each executed leg needs a minimum output above 0.
The router records its own balances of C, A and B before pulling input. After each leg, a balance below that record reverts the call. At the end, every balance must equal the record, or the call reverts.
A token pull that delivers a different amount from the one requested reverts.
Each leg approves the market for the exact amount and clears the approval after the leg.

AtomicBuyRouter_v1 does not inherit the base. It runs its own version of these checks, described below.

AtomicBuyRouter_v1

buyExactInput(firstMarket, secondMarket, amountIn, minIntermediateOut, minFinalOut, receiver, deadline)

Checks the inputs. Both markets must be contracts and different from each other. The receiver cannot be the zero address or the router.
Reads the tokens. The second market’s collateral token must equal the first market’s issuance token. The first market’s collateral token must differ from its issuance token.
Pulls amountIn of the first market’s collateral token from the caller.
Calls buyFor on the first market, with the router as receiver and minIntermediateOut as the minimum.
Calls buyFor on the second market with all the tokens the first buy minted, with receiver as receiver and minFinalOut as the minimum.
Sends any unspent collateral token and any unspent intermediate token back to the caller. Unspent amounts come from a buy that reaches the end of a curve.

Parameter	Check
`minIntermediateOut`	Above 0. The router’s increase in the intermediate token must be at or above it
`minFinalOut`	Above 0. The receiver’s increase in the final token must be at or above it
`deadline`	At or after the current block time

Reverts (errors prefixed Module__AtomicBuyRouter__): InvalidMarket, InvalidAddress, InvalidAmount, InvalidMinimumOutput, ExpiredDeadline, InvalidToken, IncompatibleMarkets, UnsupportedTokenAlias, UnsupportedTokenBehavior (the pull delivered a different amount), UnexpectedBalanceChange, InsufficientIntermediateOutput, InsufficientFinalOutput, plus any revert from either market’s buy.

AtomicSellRouter_v1

sellExactInput(amountIn, minIntermediateOut, minFinalOut, receiver, deadline)

Pulls amountIn of B from the caller.
Calls sellTo on the connected market, with the router as receiver and minIntermediateOut as the minimum. The router receives A.
Calls sellTo on the base market with all that A, with receiver as receiver and minFinalOut as the minimum.
Requires that no A or C is left on the router, and emits Sold.

Parameter	Check
`minIntermediateOut`	Above 0. The router’s increase in A must be at or above it
`minFinalOut`	Above 0. The receiver’s increase in C must be at or above it

Reverts: the shared checks, InsufficientOutput, UnexpectedResidue (A or C left on the router), plus any revert from either market’s sell.

AtomicLoopRouter_v1

loopExactInput(params)

Parameter	Meaning
`amountIn`	C pulled from the caller
`minIntermediateOut`	Minimum A from the base market buy. Above 0
`loops`	Rounds passed to the credit facility. Above 0 and at or below its maximum rounds per transaction
`consolidate`	Whether the facility merges the new loans into one
`minIssuanceOut`	Minimum total B minted across all rounds, locked tokens included. Above 0
`exit`	`ToCollateral` sells the A left over for C; `Reinvest` buys B with it
`minExitOut`	Minimum output of the exit. Must be 0 when no A is left over, and above 0 when the exit trade runs
`maxKnxFallback`	The most A the receiver accepts in place of an exit trade that rounds to zero output
`receiver`	Owner of the new loans and recipient of the exit output
`deadline`	At or after the current block time

Pulls amountIn of C from the caller.
Calls buyFor on the base market, with the router as receiver.
Calls buyAndBorrowFor on the credit facility with all that A. The new loans belong to receiver. At the end of the loop, the facility returns the A it still holds to the router (Looping).
Emits Looped with each new loan’s ID, loan amount and locked tokens.
Exits the A left over. ToCollateral calls sellTo on the base market and pays C to receiver. Reinvest calls buyFor on the connected market and mints B to receiver; this B is not locked.
Settles. C left on the router goes to the caller. A left on the router goes to receiver if it is at or below maxKnxFallback.

Reverts: the shared checks, InvalidAmount (loops is 0), ExitClosed (the exit’s direction is closed, checked even when no A is left over), InvalidMinimumOutput, InsufficientOutput, FallbackExceeded (A left over above maxKnxFallback), UnexpectedResidue (B left on the router), plus any revert from either market or the facility.

AtomicRepayRouter_v1

repayExactInput(params)

Parameter	Meaning
`loanId`	The loan to repay
`amountIn`	C pulled from the caller
`minIntermediateOut`	Minimum A from the base market buy. Above 0
`minSurplusOut`	Minimum C from selling the A not needed for the repayment. Must be 0 when no A is left, and above 0 when that sale runs
`maxKnxFallback`	The most A the caller accepts in place of a sale that rounds to zero output
`closeAndExit`	Whether to require a full repayment and sell the released B for C
`minExitKnxOut`, `minExitUsdcOut`	Minimum A from selling the released B, and minimum C from selling that A. Both above 0 when `closeAndExit` is set
`deadline`	At or after the current block time

Pulls amountIn of C from the caller.
Calls buyFor on the base market, with the router as receiver.
Reads the loan. It must be active. With closeAndExit set, the caller must be the loan’s borrower.
Calls repayFor on the credit facility with all that A. The facility repays at most the loan amount and sends the released B to the loan’s borrower, not to the caller.
With closeAndExit set, requires that the loan is closed with a loan amount of 0.
Sells the A not used for the repayment on the base market and pays C to the caller.
With closeAndExit set, pulls the released B from the caller, sells it on the connected market for A, and sells that A on the base market for C, paid to the caller.
Settles. C left on the router goes to the caller. A left on the router goes to the caller if it is at or below maxKnxFallback. Emits Repaid.

Reverts: the shared checks, InvalidLoan, CallerNotOwner, LoanNotClosed, ExitClosed (selling on the base market is closed, checked even when no A is left), InvalidMinimumOutput, InsufficientOutput, FallbackExceeded, UnexpectedResidue, plus any revert from either market or the facility, including repayFor reverting for a loan held by the early-access escrow.

Parameters

The routers have no settable parameters. The sell, loop and repay routers fix their market set in the constructor, and it cannot be changed. Each connected market’s own parameters are set as for any market (Markets and curves, Credit and looping).

Permissions the routers need

The routers have no access check of their own. Any address can call them. Each market sees the router as the caller, so the router address needs the permission for every market function it calls.

Router	Permissions on the router address
`AtomicBuyRouter_v1`	`buyFor` on both markets
`AtomicSellRouter_v1`	`sellTo` on the connected market and on the base market
`AtomicLoopRouter_v1`	`buyFor` on the base market, `buyAndBorrowFor` on the facility, `sellTo` on the base market, `buyFor` on the connected market
`AtomicRepayRouter_v1`	`buyFor` on the base market, `repayFor` on the facility, `sellTo` on the connected market and on the base market

The launch route leaves buyFor, sellTo, buyAndBorrowFor and repayFor ungranted. DeployPeripheryRouters_v1 deploys the sell, loop and repay routers for one market set, grants no permissions, and reverts unless each router already holds the permissions in the table. A grant to a router opens that function to every address that calls the router. Authority lists every role.

Edge cases

Each leg is an ordinary trade. Each market’s trading switches, fees, endowment gates and rounding apply to its leg (Markets and curves). A closed switch on either market reverts a route that trades on it.
Buy past capacity. When a buy reaches the end of a curve, the market refunds the unspent deposit to the router. AtomicBuyRouter_v1 returns it to the caller; the other routers return refunded C to the caller at settlement.
Zero-output exit. In the loop and repay routers, an exit trade whose quote rounds to zero is skipped when the A left over is at or below maxKnxFallback. That A goes to the receiver at settlement.
Released B on repayment. A repayment through AtomicRepayRouter_v1 sends released B to the loan’s borrower, whoever pays.
Whole-route revert. Any revert in any leg reverts the whole call, including the input pull.

Code

Function	File
`buyExactInput`, `_buyExactInput`	AtomicBuyRouter_v1.sol#L68-L127
`_validateRequest`, `_resolveTokens`	AtomicBuyRouter_v1.sol#L132-L193
`_buyFirst`, `_buySecond`	AtomicBuyRouter_v1.sol#L205-L271
`sellExactInput`	AtomicSellRouter_v1.sol#L37-L64
`loopExactInput`, `_emitLoans`	AtomicLoopRouter_v1.sol#L63-L118
`repayExactInput`	AtomicRepayRouter_v1.sol#L64-L107
`_repay`, `_closeExit`	AtomicRepayRouter_v1.sol#L111-L171
Constructor (market set checks)	AtomicRouterBase_v1.sol#L56-L84
`_validate`, `_minimum`, `_snapshot`, `_checkWindow`, `_pull`, `_delta`	AtomicRouterBase_v1.sol#L87-L154
`_buy`, `_sell`	AtomicRouterBase_v1.sol#L157-L196
`_exit`, `_quote`	AtomicRouterBase_v1.sol#L200-L255
`_settle`	AtomicRouterBase_v1.sol#L259-L289
`buyFor`	ReferenceCurve_v1.sol#L219-L230
`sellTo`	ReferenceCurve_v1.sol#L389-L403
`_buyOrder` (over-capacity refund)	IssuanceBase_v2.sol#L266-L340
`excludedCurve`, `excludedCredit`	LaunchPermissionSets_v1.sol#L161-L175
`_deploy`, `_assertRouters`	DeployPeripheryRouters_v1.s.sol#L106-L162

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

Overview

How it works

Deployments

Reference