# Whitelisted Swap
### 1. Overview
The **Whitelisted Swap model** defines an on-chain execution path that allows whitelisted addresses to convert SolvBTC into its underlying Reserve Asset within a single transaction.
This model is intended for protocol-level usage, including liquidation and liquidity execution scenarios, and is not exposed as a general user redemption mechanism.
***
### 2. Scope and Usage Context
Whitelisted Swap is used by **integrated protocols and authorized operators**, such as:
* Lending protocols
* Liquidation engines
* Protocol-controlled executors
* Designated on-chain adapters
Calls to this model are restricted to addresses registered in a whitelist.
#### 2.1 Architecture Overview
The diagram below illustrates the overall structure of the Whitelisted Swap model, including its core contracts, authorization boundaries, and asset flow relationships.
It provides a structural view of how the Whitelisted Swap Contract interacts with the Whitelist, Safe Vault, and governance framework, and how authorized callers execute SolvBTC-to-Reserve-Asset conversion within the system.
The diagram is intended to describe contract relationships and execution boundaries rather than a step-by-step execution sequence.
***
### 3. Whitelisted Swap Contract
The **Whitelisted Swap Contract** is the execution contract responsible for converting SolvBTC into Reserve Asset.
Its functions include:
* Receiving swap execution calls from whitelisted addresses
* Burning the specified amount of SolvBTC
* Triggering Reserve Asset transfer from the Safe Vault
* Delivering Reserve Asset to the caller
The contract:
* Does not custody Reserve Assets
* Does not perform pricing or market making
* Does not accept calls from non-whitelisted addresses
The conversion result is deterministic and defined by the SolvBTC ↔ Reserve Asset relationship.
***
### 4. Whitelist
The **Whitelist** is an access registry associated with the Whitelisted Swap Contract.
It defines which addresses are authorized to invoke swap execution.
Typical whitelist entries include:
* Lending protocol contracts
* Liquidation modules
* Authorized liquidator operators
* Protocol adapters
Whitelist validation is performed at call time. If the caller address is not registered, the call is rejected.
In addition to caller authorization, a whitelisted address may be permitted to designate one or more beneficiary addresses.
When beneficiary configuration is enabled, the Reserve Asset resulting from a swap execution can be delivered to a designated beneficiary address rather than the caller itself. Beneficiary addresses must be registered or approved under the authorization rules associated with the whitelisted caller.
This mechanism allows integrated protocols to route assets directly to internal settlement or liquidation modules while preserving access control boundaries.
***
### 5. Safe Vault Interaction
The Whitelisted Swap Contract does not hold Reserve Assets.
Instead, it interacts with the **Safe Vault**, which serves as the unified custody layer for Reserve Assets backing SolvBTC.
To enable atomic execution, the Safe Vault grants the Whitelisted Swap Contract an allowance to transfer Reserve Assets on its behalf. This allowance is configured via governance and enables the Whitelisted Swap Contract to trigger Reserve Asset transfers directly during swap execution.
During swap execution:
* The Whitelisted Swap Contract calls the Reserve Asset contract using the pre-approved allowance
* The transfer request is subject to Safe Vault internal constraints and Guardian validation
* The Reserve Asset is transferred directly from the Safe Vault to the calling address or a designated beneficiary address.
The Whitelisted Swap Contract does not have independent custody over Reserve Assets and can only access assets through the predefined allowance and validation mechanism.
***
### 6. Execution Flow
The execution flow described below represents the on-chain execution sequence within the Whitelisted Swap model.
**Execution sequence:**
1. An authorized address calls the Whitelisted Swap Contract
2. The caller address is validated against the Whitelist
3. The specified amount of SolvBTC is burned
4. A Reserve Asset transfer is triggered from the Safe Vault
5. The Reserve Asset is delivered to the calling address or a designated beneficiary address
6. The transaction completes without intermediate or deferred states
A Whitelisted Swap is executed as a single on-chain transaction.
***
### 7. Integration Pattern for Liquidation Protocols
In a typical liquidation flow within a lending protocol:
1. A borrower becomes undercollateralized
2. The protocol seizes SolvBTC collateral
3. The protocol invokes the Whitelisted Swap Contract
4. SolvBTC is converted into Reserve Asset
5. The Reserve Asset is used to settle outstanding debt
The Whitelisted Swap Contract acts as an **execution step** within the liquidation transaction.
***
### 8. Governance and Authorization
Authorization for Whitelisted Swap usage follows the **Auditors governance framework** used across the SolvBTC architecture.
Governance responsibilities include:
* Managing whitelist membership
* Configuring contract relationships with the Safe Vault
* Approving and adjusting Reserve Asset allowance for execution contracts
Governance does not participate in individual swap execution.
The Whitelisted Swap execution path can be temporarily disabled through a governance-controlled execution gate.
This mechanism allows authorized governance entities to suspend swap execution in response to abnormal conditions or operational requirements. When the execution gate is disabled, calls to the Whitelisted Swap Contract are rejected regardless of whitelist status.
The execution gate does not alter contract relationships or authorization configuration and can be re-enabled through the same governance process.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.solv.finance/solvbtc-technical-architecture/solvbtc-integration/whitelisted-swap.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.