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

# USDGPool

> USDGPool is the shared ERC-4626 vault that funds every book.

USDGPool is the shared ERC-4626 vault that funds every book. Suppliers deposit USDG and receive sUSDG, a share token whose price rises as borrowers pay interest. Stockline (the core) is the only borrower; it pulls idle cash and reports interest and repayments. Withdrawals are synchronous and limited by idle cash, and the guardian pause sets the withdrawal limit to zero.

`USDGPool` lets you:

* Deposit USDG and receive sUSDG shares
* Withdraw or redeem USDG when idle cash allows and the protocol is not paused
* Read cash, borrowed principal, and accrued interest that back the shares
* Receive donated yield from CreatorFeeRouter with no new shares minted
* Receive reserve top-ups from FeeCollector after a bad-debt write-off

Addresses per network. Every address is also on [Addresses](/resources/addresses).

| Network                 | Address                                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Robinhood Chain testnet | [0x21fF7B388b61FBE2DfD932bfD100C032C965fB0a](https://explorer.testnet.chain.robinhood.com/address/0x21fF7B388b61FBE2DfD932bfD100C032C965fB0a) |

The source code is [`src/core/USDGPool.sol`](https://github.com/stockline-xyz/contracts/blob/main/src/core/USDGPool.sol) on GitHub. The ABI is [`/abis/USDGPool.json`](/abis/USDGPool.json).

## Write methods

### borrow

```solidity theme={"system"}
function borrow(uint256 amount) external nonReentrant
```

Moves `amount` idle USDG to the core and books it as borrowed principal. Only Stockline can call it. Reverts with InsufficientCash when `amount` exceeds `cash`. Total assets do not change.

<Warning>
  Core only. Reverts with NotCore for any other caller.
</Warning>

<Note>
  Core pulls idle USDG. totalAssets stays flat: cash down, borrowed up.
</Note>

**Input parameters**

| Name   | Type      | Description               |
| ------ | --------- | ------------------------- |
| amount | `uint256` | USDG to lend to the core. |

### repay

```solidity theme={"system"}
function repay(uint256 amount) external nonReentrant
```

Pulls USDG from the core and applies it to accrued interest first, then principal. Only Stockline can call it. Reverts with RepayExceedsDebt if the received amount exceeds borrowed plus accrued interest.

<Warning>
  Core only.
</Warning>

<Note>
  Pays accrued interest first, then principal. totalAssets unchanged.
</Note>

**Input parameters**

| Name   | Type      | Description                 |
| ------ | --------- | --------------------------- |
| amount | `uint256` | USDG to pull from the core. |

### accrue

```solidity theme={"system"}
function accrue(uint256 interest) external
```

Records `interest` USDG as owed by borrowers. Only Stockline can call it, after the reserve-factor split. The share price rises immediately even though the cash arrives later on repay.

<Warning>
  Core only.
</Warning>

<Note>
  Core reports interest after the reserve-factor split. Share price rises.
</Note>

**Input parameters**

| Name     | Type      | Description                                     |
| -------- | --------- | ----------------------------------------------- |
| interest | `uint256` | Supplier interest to add, in USDG native units. |

### realizeBadDebt

```solidity theme={"system"}
function realizeBadDebt(uint256 amount) external override nonReentrant
```

Removes `amount` from what the pool expects back, accrued interest first, then principal. Only Stockline can call it. The share price falls. FeeCollector.coverBadDebt can later restore cash from the reserve.

<Warning>
  Core only. This is the last step of the bad-debt waterfall and reduces every holder's claim pro rata.
</Warning>

<Note>
  Socializes a recognized shortfall. Accrued interest first, then principal. Share price falls. SPEC: Reserve and Backstop absorb first once they exist; this is the last waterfall step.
</Note>

**Input parameters**

| Name   | Type      | Description                  |
| ------ | --------- | ---------------------------- |
| amount | `uint256` | USDG shortfall to socialize. |

### donate

```solidity theme={"system"}
function donate(uint256 amount) external nonReentrant
```

Pulls `amount` USDG from the yield distributor and adds it to cash without minting shares. Only the configured `yieldDistributor` (CreatorFeeRouter) can call it. Every sUSDG holder gains pro rata.

<Warning>
  Distributor only. Reverts with NotDistributor otherwise.
</Warning>

<Note>
  CreatorFeeRouter path. Increases cash with no new shares, so every holder earns pro rata.
</Note>

**Input parameters**

| Name   | Type      | Description     |
| ------ | --------- | --------------- |
| amount | `uint256` | USDG to donate. |

### restore

```solidity theme={"system"}
function restore(uint256 amount) external override nonReentrant
```

Pulls `amount` USDG from the caller and adds it to cash without minting shares. Permissionless. FeeCollector uses it to spend reserve on bad debt.

<Warning>
  The caller must approve USDGPool for the amount. USDG sent here is given to all share holders and cannot be recovered.
</Warning>

<Note>
  Permissionless cash add, no new shares. FeeCollector uses this to spend reserve on bad debt.
</Note>

**Input parameters**

| Name   | Type      | Description  |
| ------ | --------- | ------------ |
| amount | `uint256` | USDG to add. |

## Read methods

### totalAssets

```solidity theme={"system"}
function totalAssets() public view override returns (uint256)
```

Returns cash plus borrowed principal plus accrued interest. Backing is tracked internally, so a raw USDG transfer to the pool does not change the share price.

**Return values**

| Type      | Description                                     |
| --------- | ----------------------------------------------- |
| `uint256` | Total USDG backing sUSDG, in USDG native units. |

### maxWithdraw

```solidity theme={"system"}
function maxWithdraw(address owner) public view override returns (uint256)
```

Returns the most USDG `owner` can withdraw right now: the lesser of their share value and idle cash, or 0 while the guardian pause is active.

<Note>
  Cap assets by idle cash. Guardian pause (via core) returns 0.
</Note>

**Input parameters**

| Name  | Type      | Description       |
| ----- | --------- | ----------------- |
| owner | `address` | The share holder. |

**Return values**

| Type      | Description  |
| --------- | ------------ |
| `uint256` | USDG amount. |

### maxRedeem

```solidity theme={"system"}
function maxRedeem(address owner) public view override returns (uint256)
```

Returns the most shares `owner` can redeem right now, capped by idle cash and 0 while paused, so redeem and withdraw stay consistent.

<Note>
  Same cash/pause cap, in shares, so redeem and withdraw stay consistent.
</Note>

**Input parameters**

| Name  | Type      | Description       |
| ----- | --------- | ----------------- |
| owner | `address` | The share holder. |

**Return values**

| Type      | Description         |
| --------- | ------------------- |
| `uint256` | sUSDG share amount. |

## Events

### Borrow

```solidity theme={"system"}
event Borrow(address indexed core, uint256 amount)
```

Fires when the core draws idle USDG.

### Repay

```solidity theme={"system"}
event Repay(
    address indexed core,
    uint256 amount,
    uint256 interestPaid,
    uint256 principalPaid
)
```

Fires when the core repays, with the split between interest and principal.

### Accrue

```solidity theme={"system"}
event Accrue(uint256 interest)
```

Fires when the core reports new supplier interest.

### Donate

```solidity theme={"system"}
event Donate(address indexed from, uint256 amount)
```

Fires when the yield distributor adds USDG without minting shares.

### Restore

```solidity theme={"system"}
event Restore(address indexed from, uint256 amount)
```

Fires when anyone adds USDG through `restore`, typically FeeCollector covering bad debt.

### BadDebt

```solidity theme={"system"}
event BadDebt(uint256 amount)
```

Fires when a shortfall is socialized, with the total removed from interest and principal.

## Errors

### NotCore

```solidity theme={"system"}
error NotCore()
```

Only Stockline can borrow, repay, accrue, or realize bad debt.

### NotDistributor

```solidity theme={"system"}
error NotDistributor()
```

Only the yield distributor can donate.

### ZeroAddress

```solidity theme={"system"}
error ZeroAddress()
```

The core or distributor address was zero at deployment.

### ZeroAmount

```solidity theme={"system"}
error ZeroAmount()
```

An amount was zero, or a transfer delivered zero tokens.

### InsufficientCash

```solidity theme={"system"}
error InsufficientCash()
```

The requested amount exceeds idle cash.

### RepayExceedsDebt

```solidity theme={"system"}
error RepayExceedsDebt()
```

The core tried to repay more than borrowed plus accrued interest.