> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Stablecoin Delegate Contracts

> LP-controlled settlement domains for custody, fees, compliance, and liquidity

## Overview

Stablecoin delegates connect `MultiliquidSwap` to a specific Liquidity Provider (LP). Each delegate defines how assets move, which collateral it accepts, where reserves are held, how LP fees are configured, and which administrative controls apply.

The selected `stablecoinDelegateID` gives every route a clear LP domain. That domain owns the settlement policy even when the route exchanges two RWAs or two stablecoins.

<CardGroup cols={2}>
  <Card title="LP-Owned Configuration" icon="sliders">
    LP admins manage accepted assets, fee schedules, custody, liquidity, and
    delegate-level controls.
  </Card>

  <Card title="Atomic Settlement" icon="arrows-rotate">
    Delegates move or mint assets only when called by the registered
    `MultiliquidSwap` contract.
  </Card>

  <Card title="Transparent Reserves" icon="building-columns">
    Hot custody and informational cold-storage addresses are directly readable
    on-chain.
  </Card>

  <Card title="Composable Liquidity" icon="bolt">
    Delegates can designate an auto-liquidity stablecoin for prefund and sweep
    workflows.
  </Card>
</CardGroup>

**Base contract**: `src/prod/StablecoinDelegateBase.sol`

## Delegate Architecture

`MultiliquidSwap` calculates resolved amounts and calls one of four settlement methods. The delegate then performs the token-specific transfer, mint, or burn operations.

### Production Delegate Families

| Family                 | Settlement model                                                              |
| ---------------------- | ----------------------------------------------------------------------------- |
| Balance sheet          | Transfers existing inventory between users, custody, and the protocol vault   |
| Mint/burn              | Mints the delegated stablecoin on issuance and burns it on redemption         |
| Yield-bearing Treasury | Mints and burns Treasury while tracking credits, rates, and yield multipliers |

All families inherit the same custody, LP-admin, whitelist, fee, blacklist, pause, and upgrade framework.

## Settlement Interface

```solidity theme={null}
struct DelegateParams {
    address user;
    address receiver;
    address vault;
    uint256 protocolFeeAmt;
    uint256 lpFeeAmt;
    address assetInAddress;
    uint256 assetInAmount;
    address assetOutAddress;
    uint256 assetOutAmount;
}
```

| Function              | Route family            | Delegate responsibility                                                       |
| --------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `deployStablecoin`    | RWA → stablecoin        | Receive the RWA and deliver the configured stablecoin                         |
| `receiveStablecoin`   | Stablecoin → RWA        | Receive or burn stablecoin and deliver the RWA                                |
| `exchangeRWAs`        | RWA → RWA               | Receive one accepted RWA and deliver another                                  |
| `exchangeStablecoins` | Stablecoin → stablecoin | Exchange the delegated stablecoin against an accepted counterparty stablecoin |

Each method is callable only by the role assigned to `MultiliquidSwap`, is non-reentrant, and respects delegate pause and blacklist state.

### User and Receiver

`user` is the source of the input asset and `receiver` is the destination for the output asset. Delegates validate both identities and send output directly to the requested receiver.

### Protocol and LP Fees

`protocolFeeAmt` contains the protocol amounts resolved by `MultiliquidSwap`. `lpFeeAmt` contains the explicit LP fee for the route. The concrete delegate determines whether those amounts are transferred from custody, taken from input, or minted according to the stablecoin's settlement model.

## Balance-Sheet Settlement

`BalanceSheetStablecoinDelegate` uses pre-existing liquidity:

* RWA inputs move from the user to `balanceSheetCustodyAddress`.
* RWA outputs move from RWA custody to the receiver.
* Stablecoin inputs move into `stablecoinCustodyAddress`.
* Stablecoin outputs and applicable protocol fees move out of stablecoin custody.
* RWA and stablecoin custody accounts approve the delegate as ERC-20 spender.

This model supports stablecoins that do not expose mint and burn permissions to the delegate.

## Mint-and-Burn Settlement

`MintBurnStablecoinDelegate` represents integrations that expose controlled mint and burn authority:

* RWA → stablecoin routes mint stablecoin output to the receiver.
* Stablecoin → RWA routes burn the user's delegated stablecoin.
* RWA → RWA routes can mint protocol and LP fees without moving the delegated stablecoin through the user's wallet.
* Stablecoin → stablecoin routes mint or burn the delegated stablecoin and custody the counterparty stablecoin.

Concrete implementations can adapt the base behavior to a token's native mint and burn interface.

## Treasury Yield Delegate

`TreasuryDelegate` combines stablecoin settlement with on-chain yield accounting.

### Credits and Yield

* `credits[user]` tracks released backing credits.
* New deposits enter a 24-hour withheld-credit queue.
* `totalWithheldCredits[user]` provides the aggregate pending amount.
* `yieldMultiplier[user]` converts released credits into effective redeemable value.
* `lastAccrualDay[user]` records the user's synchronized rate day.

RWA-backed deposits begin earning from their deposit timestamp. Stablecoin-backed deposits apply the configured earning-start rules. Withheld credits remain redeemable at face value and merge into released credits as they mature.

### Daily Rates

Rate posters submit sequential gross APY values. The delegate subtracts the portfolio management fee and stores the resulting net APY and derived daily compounding rate.

```solidity theme={null}
function postDailyRate(uint256 dayNumber, uint256 grossRate) external;
function correctDailyRate(uint256 dayNumber, uint256 grossRate) external;
```

The delegate supports an optional maximum daily rate and a bounded fallback window for partial-day stablecoin withdrawal yield.

### Interest Accrual

```solidity theme={null}
function accrueInterest(
    address user,
    uint256 maxDays,
    uint256 maxRecords
) external returns (
    uint256 daysProcessed,
    uint256 recordsProcessed,
    bool daysComplete,
    bool recordsComplete
);
```

`maxDays` bounds posted-rate processing and `maxRecords` bounds withheld-credit merging. Both values must be nonzero. `batchAccrueInterest` synchronizes multiple users without explicit per-user limits.

Swap settlement synchronizes the relevant user's Treasury state before final pricing. Read-only `quoteSwap` uses stored state without changing it.

## LP Administration

LP admins are stored independently from OpenZeppelin role membership and can add or remove other LP admins.

### Asset Eligibility

```solidity theme={null}
function whitelistRWA(address rwa, bool accepted) external;
function whitelistStablecoin(address stablecoin, bool accepted) external;
```

The RWA whitelist determines which RWA tokens the LP domain will accept or deliver. The stablecoin whitelist determines which counterparty stablecoins can be exchanged against the delegated stablecoin.

These delegate lists complement protocol-level asset acceptance, RWA recipient whitelist adapters, token-native compliance, and optional RWA delegates.

### Fee Configuration

LP admins configure WAD-scaled rates through the delegate:

```solidity theme={null}
function setRWADiscountRate(bytes32 rwaID, uint256 rate) external;
function setRWARedemptionFee(bytes32 rwaID, uint256 rate) external;
function setStablecoinAcceptanceFee(address stablecoin, uint256 rate) external;
function setStablecoinRedemptionFee(address stablecoin, uint256 rate) external;
```

The delegate forwards these settings to its registered stablecoin domain in `MultiliquidSwap`. Rates must remain below `1e18`.

### Auto-Liquidity

```solidity theme={null}
function setAutoLiquidityStablecoinID(
    bytes32 autoLiquidityStablecoinID
) external;
```

The selected asset is used by `MultiliquidSwap` for eligible prefund and sweep legs. Passing `bytes32(0)` disables automatic liquidity for the delegate.

### Custody

```solidity theme={null}
function setRWACustodyAddress(address custodyAddress) external;
function setStablecoinCustodyAddress(address custodyAddress) external;
```

Both hot custody addresses must be configured before settlement. They can point to separate accounts and are exposed independently on-chain.

Delegates also maintain informational reserve disclosures:

```solidity theme={null}
function getRWAColdStorageAddresses()
    external
    view
    returns (address[] memory);

function getStablecoinColdStorageAddresses()
    external
    view
    returns (address[] memory);
```

LP admins can add and remove entries for both reserve categories.

### Delegate Controls

LP admins can:

* Apply an additional delegate-level blacklist
* Pause and unpause LP settlement
* Withdraw stablecoin held directly by the delegate
* Update hot custody accounts
* Manage LP-admin membership

Multiliquid's `PAUSE_ROLE` has a separate `pauseMultiliquid` and `unpauseMultiliquid` path for protocol operations.

## Token Allowances

Stablecoin delegates execute ERC-20 `transferFrom` calls and are the token spender for user and custody transfers.

Typical integrations configure:

* User allowance to the selected delegate for each input token
* RWA custody allowance to the delegate for RWA output inventory
* Stablecoin custody allowance to the delegate for stablecoin output and fee inventory

Protocol-level standing swap allowances and EIP-712 permits authorize the operator; they do not replace ERC-20 token allowances.

## Access Control

| Authority                   | Capabilities                                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `DEFAULT_ADMIN_ROLE`        | UUPS upgrades and OpenZeppelin role administration                                           |
| LP admin                    | Whitelists, fee schedules, custody, reserve disclosures, LP blacklist, and LP pause controls |
| `MULTILIQUID_SWAP_CONTRACT` | Settlement entrypoints                                                                       |
| `PAUSE_ROLE`                | Protocol pause and unpause path                                                              |
| Treasury `RATE_POSTER_ROLE` | Sequential daily-rate posting                                                                |
| Treasury `OPERATOR_ROLE`    | Rate correction and yield operating parameters                                               |

## Core Events

The base delegate emits events for:

* RWA and stablecoin whitelist updates
* RWA discounts and redemption fees
* Stablecoin acceptance and redemption fees
* Auto-liquidity configuration
* Hot custody changes
* Cold-storage additions and removals
* Delegate blacklist changes
* LP-admin membership
* Pause, unpause, and upgrades

`TreasuryDelegate` additionally emits daily-rate, interest-accrual, credit, management-fee, and yield-multiplier events.

<Card title="Next: RWA Delegate Contracts" icon="file-code" href="/evm/contracts/rwa-delegate">
  Explore asset-specific stateful risk controls
</Card>