> ## 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.

# AuctionYield

> AuctionYield pays USDG to auction buyers who keep their won STK staked, for a fixed term.

AuctionYield pays USDG to auction buyers who keep their won STK staked, for a fixed term. After every auction bid has exited, the post-auction script writes a merkle root of (buyer, won amount) and locks it here once. A buyer proves their leaf and stakes STK up to that amount. Every `harvest` from ProtocolSupply calls `notifyReward`, and stakers share it pro rata. Unstaking stops future yield. After `termEnd`, new stakes and new rewards revert; unstake and claim stay open forever.

`AuctionYield` lets you:

* Stake won STK against a merkle proof, up to the won amount
* Earn a pro rata share of every harvest while staked
* Claim pending USDG, or unstake and claim in one call
* Read the root, the term end, and what an account is owed

This contract is not deployed on a listed network yet. Watch [Addresses](/resources/addresses).

| Network                 | Address      |
| ----------------------- | ------------ |
| Robinhood Chain testnet | Not deployed |
| Robinhood Chain         | Not deployed |

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

## Write methods

### setRoot

```solidity theme={"system"}
function setRoot(bytes32 merkleRoot_) external
```

Locks the buyer merkle root. Only the root setter (the deployer) can call it, once. Reverts with RootAlreadySet on a second call and InvalidRoot for zero.

<Warning>
  One shot. The root cannot change after this.
</Warning>

**Input parameters**

| Name         | Type      | Description                                                                          |
| ------------ | --------- | ------------------------------------------------------------------------------------ |
| merkleRoot\_ | `bytes32` | Root of leaves `keccak256(bytes.concat(keccak256(abi.encode(account, wonAmount))))`. |

### stake

```solidity theme={"system"}
function stake(
    uint256 amount,
    uint256 wonAmount_,
    bytes32[] calldata proof
) external nonReentrant
```

Verifies `(msg.sender, wonAmount_)` against the root, then pulls `amount` STK and adds it to the stake. Total staked per account cannot exceed the won amount. Harvests pending yield first. Reverts with TermEnded after `termEnd`, RootNotSet before the root, InvalidProof, WonAmountMismatch if a later call passes a different won amount, and StakeCapExceeded above the cap.

<Warning>
  The caller must approve AuctionYield for `amount`. Rewards distributed while nobody was staked go to the first staker after that gap.
</Warning>

**Input parameters**

| Name        | Type        | Description                                                         |
| ----------- | ----------- | ------------------------------------------------------------------- |
| amount      | `uint256`   | STK to stake, 18 decimals.                                          |
| wonAmount\_ | `uint256`   | The STK this account won in the auction, from the published leaves. |
| proof       | `bytes32[]` | Merkle proof for the leaf.                                          |

### unstake

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

Harvests pending yield, then returns `amount` STK to the caller. Reverts with InsufficientStake above the staked balance and ZeroAmount for 0.

<Note>
  Unstaked STK earns nothing. Restaking is allowed until `termEnd`, up to the won amount.
</Note>

**Input parameters**

| Name   | Type      | Description      |
| ------ | --------- | ---------------- |
| amount | `uint256` | STK to withdraw. |

### notifyReward

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

Pulls `amount` USDG from the caller and distributes it across current stakers. If nobody is staked, the amount is held as pending for the next staker. Reverts with TermEnded after `termEnd`. Permissionless, but in practice only ProtocolSupply.harvest calls it.

**Input parameters**

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

### claim

```solidity theme={"system"}
function claim() external nonReentrant
```

Transfers all pending USDG to the caller. Does nothing if nothing is owed.

## Read methods

### pending

```solidity theme={"system"}
function pending(address account) external view returns (uint256)
```

Returns the USDG `account` could claim right now.

**Input parameters**

| Name    | Type      | Description |
| ------- | --------- | ----------- |
| account | `address` | The staker. |

**Return values**

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

## Events

### RootSet

```solidity theme={"system"}
event RootSet(bytes32 merkleRoot)
```

Fires once when the merkle root is locked.

### Staked

```solidity theme={"system"}
event Staked(
    address indexed account,
    uint256 amount,
    uint256 wonAmount
)
```

Fires when an account stakes STK, with the won amount proven.

### Unstaked

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

Fires when an account withdraws STK.

### Distributed

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

Fires on every notifyReward.

### Claimed

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

Fires when USDG is paid out, by claim or by the harvest inside stake and unstake.

## Errors

### ZeroAddress

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

A constructor address was zero.

### ZeroAmount

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

An amount was zero.

### InvalidTerm

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

termEnd was not in the future at deployment.

### NotRootSetter

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

Only the root setter can call setRoot.

### RootAlreadySet

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

setRoot was called twice.

### RootNotSet

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

stake was called before the root was locked.

### InvalidRoot

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

setRoot got a zero root.

### TermEnded

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

stake or notifyReward was called after termEnd.

### InvalidProof

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

The merkle proof does not match the root.

### WonAmountMismatch

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

The won amount differs from the one recorded on the first stake.

### StakeCapExceeded

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

The stake would exceed the won amount.

### InsufficientStake

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

The unstake amount exceeds the staked balance.