> For the complete documentation index, see [llms.txt](https://docs.rujira.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rujira.network/core-products/rujira-amm/base-layer-virtualization-strategy-vs.md).

# Base Layer Virtualization Strategy (VS)

The Base Layer Virtualization Strategy (VS) connects THORChain’s liquidity pools with Rujira Trade through two smart contracts. **Swap** turns Base Layer liquidity into virtual quotes that traders can fill on Rujira Trade. **Arb** trades price differences between Rujira Trade and the Base Layer pools, helping align prices across the two layers.

{% hint style="warning" %}
The latest two-contract design is being tested. This page explains its intended operation and is still subject to change. Availability and configuration depend on the deployment.
{% endhint %}

### Why two contracts?

THORChain executes native swaps through its swap queue at the end of the block. An App Layer contract cannot submit a native swap and immediately use its proceeds in the same contract execution. The VS bridges this timing gap by paying the App Layer side first and replenishing those funds through the Base Layer swap afterward.

Arbitrage also supports THORChain's pricing. Swaps change the balance of assets in Base Layer pools, which can move pool prices away from the wider market. Arb uses eligible Rujira Trade liquidity to trade against price differences between the layers and help rebalance those pools. When Rujira Trade liquidity reflects the wider market (e.g. through DCL strategies which quote based on oracle prices), this helps pool prices track market prices more closely. That can improve the quotes THORChain offers to swappers and make it more competitive with other trading venues.

The two contracts use different funding and pricing methods:

<table><thead><tr><th width="175"></th><th>Swap</th><th>Arb</th></tr></thead><tbody><tr><td>Role</td><td>Provide Base Layer liquidity as virtual quotes on the Rujira Trade orderbook. Support liquidity depth for large market orders and liquidations.</td><td>Capture price differences between Rujira Trade liquidity and Base Layer pools. Support Base Layer quotes and execution, and internalize arbitrage profits between THORChain and Rujira.</td></tr><tr><td>Trigger</td><td>A trade consumes a virtual quote.</td><td>A scheduled Rujira Trade arbitrage execution finds a suitable opportunity.</td></tr><tr><td>Funding</td><td>Available contract balances, supplemented by borrowing from registered lending vaults.</td><td>Funds held by the Arb contract (no borrowing).</td></tr><tr><td>Pricing</td><td>Quotes derived from current pool depths, with a retained margin and any AMM maker fee.</td><td>Exact trade amounts priced using the native queue, conservative pool-change estimates and execution-capacity checks.</td></tr><tr><td>Capital requirement</td><td>Can operate using authorized borrowing from lending vaults, without a separate LP position.</td><td>Must be funded before it can trade.</td></tr></tbody></table>

### Swap: bringing Base Layer liquidity to the orderbook

#### How it works

Swap reads the relevant THORChain pools and converts their liquidity into a series of virtual quotes on Rujira Trade. These quotes can sit alongside limit orders, oracle orders and liquidity supplied by other market-making strategies (CCL and DCL).

When a trader accepts a quote:

1. **Rujira Trade sends the input asset to Swap.** For example, a trader selling BTC for USDT supplies BTC to the strategy through Rujira Trade.
2. **Swap pays the output immediately.** It uses its available USDT balance first. If that is insufficient, it borrows the shortfall from the registered USDT lending vault, within its borrowing limits.
3. **Swap submits a native hedge.** The BTC is queued for conversion into USDT through the Base Layer pools. The proceeds return to Swap.
4. **Settled funds become available for repayment.** A subsequent repayment execution can use those funds to reduce borrowing. Funds remaining after the payout, AMM maker fee and borrowing costs accumulate in Swap as its reserve. The reserve helps fund future trades and absorb losses when native settlement returns less than expected due to intrablock activity.

Swap checks for repayable balances after each App Layer payout. The new native hedge has not settled at that point. When its proceeds arrive, they increase Swap’s balance but do not trigger repayment. A later swap or a permissionless repay call can repay debt using funds not reserved for queued native inputs. Repayment is submitted only when the available amount exceeds 1,000 bank units: 0.00001 BTC or USDT for eight-decimal secured assets.

#### Example: selling BTC for USDT

Suppose the pool-based quote for **0.01 BTC** is **1,000 USDT**. For this accepted quote, assume a **30 bps reserve fee** and a **2.5 bps AMM maker fee**:

| Item                                       |          Amount |
| ------------------------------------------ | --------------: |
| Pool-based expected return                 |   1,000.00 USDT |
| Margin reserved by Swap: 0.30%             |       3.00 USDT |
| AMM maker fee: 0.025%                      |       0.25 USDT |
| Output paid to Rujira Trade for the trader | **996.75 USDT** |

If Swap has no USDT available, it borrows **997 USDT** to fund the Rujira Trade payout and AMM maker fee. If the native swap subsequently returns the expected **1,000 USDT**, a later repayment execution can repay the **997 USDT** principal and leave **3 USDT**, less borrowing interest.

The reserve fee is a buffer, not guaranteed profit. If the native swap instead returns **996.50 USDT**, the trade has a **0.50 USDT loss before interest** relative to its 997 USDT outlay. Earlier accumulated reserves may absorb that loss. The `reserve_fee` is periodically reviewed and adjusted to help cover settlement losses and borrowing costs over time.

Actual virtual quotes are calculated in successive price levels. This example assumes the accepted payout shown above and omits separate Rujira Trade fees.

#### Main Swap parameters

The values below are illustrations only. **One basis point (bp) is 0.01%; 100 bps is 1%.** Decimal rates use `"0.003"` for 0.30%, while fields ending in `_bps` use whole basis points.

<table><thead><tr><th width="180">Parameter</th><th>What it controls</th><th>Example</th></tr></thead><tbody><tr><td><code>reserve_fee</code></td><td>Margin deducted when building virtual quotes to leave a local reserve for settlement differences and borrowing costs. Increasing it generally makes quotes less competitive but provides a larger buffer against settlement losses.</td><td><code>"0.003"</code> = 30 bps: a 1,000 USDT gross quote includes a 3 USDT reserve margin.</td></tr><tr><td><code>fee</code></td><td>AMM maker fee rate and recipient. This is paid out separately and does not accumulate in Swap's reserve.</td><td><code>["0.00025", "&#x3C;recipient>"]</code> = 2.5 bps, or 0.25 USDT on a 1,000 USDT gross quote.</td></tr><tr><td><code>max_borrow_ratio</code></td><td>Caps the borrowed part of a fill relative to the output side of the relevant native pool. Existing inventory can fund additional output.</td><td><code>"0.25"</code> = 25%. An output pool depth of 20,000 USDT gives a 5,000 USDT pool-based borrowing cap, subject to vault credit and available liquidity.</td></tr><tr><td><code>min_borrow_amount</code></td><td>Minimum loan size when borrowing is needed. It avoids loans too small for the lending vault's share accounting. It is not a minimum trade size.</td><td><code>"100"</code> means 100 bank units: 0.000001 USDT or BTC for eight-decimal secured asset balances.</td></tr><tr><td><code>spread_bps</code></td><td>Sets the initial input chunk used to construct virtual quote levels from pool depth. Despite its name, it is not a fixed price surcharge.</td><td>On a single-hop route with 100 BTC input depth, <code>1</code> gives an initial 0.01 BTC input chunk. Two-hop sizing also accounts for the RUNE depth of both pools.</td></tr><tr><td><code>stream_step_ratio</code></td><td>Multiplier applied to the input chunk for each successive virtual quote level, before liquidity limits.</td><td><code>"0.99"</code> produces chunks of 100, 99 and 98.01 units.</td></tr><tr><td><code>max_stream_length</code></td><td>Maximum streaming length requested for the native hedge. This affects settlement timing, not the number of displayed quote levels.</td><td><code>1</code> requests a single sub-swap. Longer streaming can extend exposure and borrowing time.</td></tr><tr><td><code>arb_guard</code></td><td>Arb contract used to check that a native hedge submitted during scheduled EndBlock execution preserves earlier Arb commitments.</td><td>Required for Swap to issue native swaps in that execution context. Ordinary user swaps can operate without it.</td></tr></tbody></table>

Quote construction and sizing are defined in the [quote implementation](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-swap/src/quote.rs) and [route implementation](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-swap/src/route.rs). The [Swap interface](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/packages/rujira-rs/src/interfaces/thorchain_swap.rs) defines the configuration fields.

Two additional permissions determine where Swap can operate. Each Rujira Trade market must be registered with Swap and configure Swap as a market maker. Each borrowed asset also needs a registered lending vault that authorizes Swap as a borrower. The vault's absolute borrowing allowance and available liquidity apply alongside `max_borrow_ratio`; registering a vault alone does not grant borrowing credit.

### Arb: connecting prices across the two layers

#### How it works

Arb uses assets already held in the contract to pay Rujira Trade immediately. It receives the other asset in return and swaps it through the Base Layer pools to replenish what it paid out. Any realized surplus increases Arb’s inventory; a settlement shortfall reduces it. Arb needs spendable balances of both assets to trade in both directions.

For example, if BTC can be bought more cheaply from Rujira Trade liquidity than it can be sold into the Base Layer pools, Arb and Rujira Trade can complete the two sides of that opportunity. The reverse direction works when BTC is cheaper on the Base Layer.

Repeated arbitrage helps keep Base Layer pool prices aligned with the market prices reflected on Rujira Trade, supporting more competitive quotes for THORChain users.

The trade must cover the configured margins and execution costs, and its size is limited by available liquidity, funded inventory and native execution conditions.

Arb estimates its native hedge return using pool balances and supported swaps already in THORChain’s queue. It allows for uncertainty in how those swaps may execute. Rujira Trade compares trade sizes and directions against its eligible liquidity, while Arb quotes an exact input and output amount.

An optional preparation step gathers and validates current data across four scheduled jobs, immediately before arbitrage runs in the same block. Splitting the work helps it fit within THORChain’s EndBlock gas limits. Preparation does not lock in a price or guarantee a trade.

Arb checks the modeled queue and native execution capacity against its hedge commitments. If it cannot model the queue within its supported limits, it offers no executable quote. If execution checks fail, the scheduled contract execution rolls back. Native settlement happens afterward, so the App Layer trade and Base Layer hedge are not a single atomic transaction. These checks rely on a compatible THORChain execution model and later scheduled contracts preserving accepted hedges. [Arb execution model](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-arb/src/planner.rs), [prepared queue checks](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-arb/src/bounded_queue.rs) and [state preparation](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-arb/src/prepared.rs)

#### Example: BTC is cheaper on Rujira Trade

Assume Rujira Trade has an eligible order selling exactly **0.01 BTC for 990 USDT**, with no further liquidity consumed and zero Rujira Trade fees in this example. Arb projects that selling that BTC through the native queue will return **1,000 USDT**, after applicable Base Layer costs. Its reserve fee is **1 bp** and its AMM maker fee is **zero**.

| Step                                        | Result                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Arb calculates its exact lot                | Receive 0.01 BTC from Rujira Trade and pay Rujira Trade **999.90 USDT**, retaining a projected 0.10 USDT margin.    |
| Rujira Trade matches its internal liquidity | The BTC seller receives **990 USDT**. The remaining **9.90 USDT** is Rujira Trade's arbitrage profit.               |
| Arb funds the settlement                    | Arb uses **999.90 USDT already held in the contract**. It receives the 0.01 BTC and queues it for the native hedge. |
| The native hedge settles as projected       | Arb receives **1,000 USDT**, replenishing its inventory with a **0.10 USDT increase**.                              |

The **9.90 USDT Rujira Trade surplus** is captured as protocol revenue and shared between Rujira and THORChain per the applicable [Rujira Trade fee-sharing rules](https://docs.rujira.network/core-products/rujira-trade.md#fees-and-fee-sharing-with-thorchain-base-layer). The **0.10 USDT Arb reserve margin** stays in Arb and can increase its capacity for future trades. A zero AMM maker fee does not redirect Rujira Trade's surplus into Arb. [Rujira Trade arbitrage accounting](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-fin/src/arb_lot.rs)

With a **30 bps reserve fee**, the same trade would instead retain a projected **3 USDT in Arb** and leave **7 USDT as Rujira Trade** protocol revenue, assuming the same trade size and native return.

For a fixed lot, increasing Arb's reserve fee leaves less output available to Rujira Trade. That can make a marginal opportunity unprofitable for Rujira Trade, or cause a different size or direction to be selected. Lowering the fee leaves more of the opportunity on Rujira Trade and less retained capital in Arb.

This example omits rounding. Real opportunities may produce Rujira Trade surplus in either asset or both. The retained Arb margin is projected; its realized amount depends on native settlement.

#### Main Arb parameters

These example values illustrate the controls; they are not requirements for every deployment.

<table><thead><tr><th width="155">Parameter</th><th>What it controls</th><th>Example</th></tr></thead><tbody><tr><td><code>max_offer_bps</code></td><td>Maximum candidate input as a fraction of the native input pool's depth. This limits the size explored; it does not require Arb to trade that amount. Rujira Trade liquidity, funded inventory and execution checks can impose smaller limits.</td><td><code>250</code> = 2.5%. With 100 BTC of input depth, the candidate cap is 2.5 BTC. For RUNE input, the relevant RUNE-side depth is used.</td></tr><tr><td><code>reserve_fee</code></td><td>Portion of projected native output withheld from the Rujira Trade payout to accumulate capital inside Arb.</td><td><code>"0.0001"</code> = 1 bp: retain a projected 0.10 USDT from a 1,000 USDT native return.</td></tr><tr><td><code>fee</code></td><td>AMM maker fee rate and recipient, separate from both Arb's retained reserve and Rujira Trade's arbitrage profit.</td><td><code>["0", "&#x3C;recipient>"]</code> pays no AMM maker fee. A 2.5 bps fee would pay 0.25 USDT from a 1,000 USDT projected native return.</td></tr><tr><td><code>max_queue</code></td><td>Limits how many queued swaps Arb can analyse before offering a trade. The count includes its proposed native hedge. Allowed values: 1–128.</td><td><p><code>128</code> allows 127 existing entries plus that hedge.</p><p>With preparation, entries that are not eligible in the current block can be excluded. If the applicable count exceeds the limit, Arb offers no executable quote.</p></td></tr></tbody></table>

### Supported assets and operating limits

An asset needs a supported native route as well as the relevant contract registration. Arb's current implementation recognizes RUNE, supported secured assets, and the native RUJI and TCY denominations. This does not automatically enable every native token or every Rujira Trade pair. [Asset validation and routing](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-thorchain-arb/src/planner.rs)

Swap's usable liquidity depends on inventory, lending capacity and pool availability. Arb additionally depends on funded payout inventory, compatible queue conditions and scheduled execution. A price difference between the layers does not by itself mean that Arb can execute it, and an arbitrage request can complete without a trade.

Preparation lets Arb handle a wider range of queue conditions, but limits still apply to how many queue entries and pools it can analyse. Unsupported queue effects, insufficient execution capacity or an unfavorable estimated return can still prevent a trade. Without preparation, Arb supports a narrower range of queue conditions.

### Where the revenue goes

<table><thead><tr><th width="372">Revenue or cost</th><th>Treatment</th></tr></thead><tbody><tr><td>Swap's realized reserve surplus</td><td>Remains in Swap after payouts, AMM maker fees and borrowing costs. It can absorb future settlement losses.</td></tr><tr><td>Arb's realized reserve surplus</td><td>Remains in Arb, increasing the inventory available for future opportunities.</td></tr><tr><td>A configured Swap or Arb AMM maker fee</td><td>Captured as protocol revenue and shared between Rujira and THORChain</td></tr><tr><td>Rujira Trade arbitrage profit</td><td>Captured as protocol revenue and shared between Rujira and THORChain</td></tr><tr><td>THORChain swap fees</td><td>Costs of execution. Deducted from the expected output from Base Layer swaps.</td></tr><tr><td>Borrowing interest</td><td>Reduces Swap’s net reserve surplus and accumulates while borrowing remains outstanding.</td></tr></tbody></table>

The contracts keep separate balances. A reserve accumulated in one contract does not automatically cover losses or fund trades in the other. The word **reserve** here refers to funds retained by the VS contracts, not THORChain's native Reserve module. Rujira Trade's distribution mechanism is defined in its [arbitrage settlement source](https://gitlab.com/thorchain/rujira/-/blob/de98fdbb292c121a8ace703211eb5a4653538314/contracts/rujira-fin/src/contract.rs).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rujira.network/core-products/rujira-amm/base-layer-virtualization-strategy-vs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
