> For the complete documentation index, see [llms.txt](https://docs.rh.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rh.fun/for-developers/claiming-market-rewards.md).

# Withdrawals & Vault Interactions

User-facing withdrawals and vault interactions depend on the token's configuration:

* **Dividend withdrawals** — for tax markets with the Holder Dividend channel enabled.
* **Vault interactions** — for markets using SnowBall, BurnDividend, Gift, or Split Vault.

***

## Dividend Withdrawal

For tax-enabled markets with the Holder Dividend channel active, discover `dividendContract` from `NewRHTaxTokenParams`, then call:

```solidity
function withdrawDividends() external;
```

***

## SnowBall Vault

SnowBall Vaults are fully automated. The Keeper Bot calls `snowball(quoteAmt, amountOutMin)` to execute buybacks. No user interaction is needed.

**Key functions:**

```solidity
// Keeper-only: execute buyback & burn
function snowball(uint256 quoteAmt, uint256 amountOutMin) external;

// View: vault statistics (total spent, total burned)
function vaultStats() external view returns (uint256 totalQuoteSpent, uint256 totalTokensBurned);
```

***

## BurnDividend Vault

### Burning Tokens

Holders burn their tokens to earn dividend shares. Burned tokens are permanently destroyed.

```solidity
// Burn tokens to earn dividend shares
function burn(uint256 amount) external;
```

### Claiming Dividends

Once the Vault is in Dividend mode, holders can claim accumulated ETH rewards:

```solidity
// Claim accumulated dividends to your address
function claimReward() external;

// Claim accumulated dividends to a specified address
function claimRewardTo(address recipient) external;
```

If a transfer fails, the amount is queued in `queuedReward[user]` and can be claimed again later.

### View Functions

```solidity
// Check if the vault is in Dividend mode
function isDividendMode() external view returns (bool);

// Vault statistics
function totalRewardReceived() external view returns (uint256);
function totalRewardDistributed() external view returns (uint256);
function totalRewardClaimed() external view returns (uint256);
function totalBurned() external view returns (uint256);

// Buyback phase statistics
function buybackCount() external view returns (uint256);
function totalBuybackQuote() external view returns (uint256);
function totalBuybackTokensBurned() external view returns (uint256);
```

***

## Gift Vault

### Managing via Relayer

Gift Vault management is done through X (Twitter) tweets. After posting a valid tweet, submit the proof to the Relayer API:

```
POST {relayerEndpoint}/submit
Content-Type: application/json

{
  "tax_token": "0x...",
  "tweet_id": "..."
}
```

**Rate limit:** 1 request per minute per IP.

### On-Chain Verification

Before submitting to the Relayer, verify the tweet on-chain:

```solidity
// Check if the vault can be managed (view function, no gas)
function canManageVault(address taxToken, string calldata xHandle, string calldata tweetId)
    external view returns (bool canManage, string memory errorMessage);
```

**Note:** `xHandle` must be lowercase.

### Key Functions

```solidity
// View: current vault state
function state() external view returns (State); // ACCUMULATING, STREAMING, FALLBACK_SNOWBALL

// View: current streaming target address
function streamingTarget() external view returns (address);

// View: historical proof records
function getHistoricalProofs(uint256 offset, uint256 limit) external view returns (ProofRecord[] memory);

// Keeper: execute snowball (only in FALLBACK_SNOWBALL state)
function snowball(uint256 quoteAmt) external;
```

### Vault States

| State               | Value | Description                                                               |
| ------------------- | ----- | ------------------------------------------------------------------------- |
| `ACCUMULATING`      | 0     | Waiting for the Gift Owner's first tweet.                                 |
| `STREAMING`         | 1     | Tax revenue is forwarded to the Gift Owner's specified address.           |
| `FALLBACK_SNOWBALL` | 2     | Gift Owner was inactive for 7 days. Vault now operates as buyback & burn. |

***

## Split Vault

Split Vault distributes tax revenue among multiple recipients based on configured percentage shares. Distribution happens automatically when ETH enters the Vault, with manual fallback if needed.

### Claiming Funds

If automatic distribution fails for a recipient, they can claim manually:

```solidity
// Trigger distribution to all recipients
function dispatch() external;

// Single recipient claims their accumulated balance
function claim(address user) external;
```

### View Functions

```solidity
// Get all recipients and their balances
function getRecipientsInfo() external view returns (RecipientInfo[] memory);

// Vault description
function description() external view returns (string memory);
```

### Events

```solidity
// Emitted when ETH is received and accounted
event SplitVaultDistributed(address indexed taxToken, uint256 amount);

// Emitted when a recipient receives funds (kind: 0 = dispatch, 1 = claim)
event SplitVaultDispatched(address indexed taxToken, address indexed recipient, uint256 amount, uint8 kind);
```

***

## Creating Tokens with Vaults

Vaults are created as part of token creation by setting `marketVaultFactory` and `marketVaultData` in `CreateParams` when calling `createRHToken`. The Factory calls the specified vault factory's `newVault()` internally, and the resulting vault address receives market-bucket tax revenue.

### Vault Factory Addresses

| Vault Type   | Factory Address                              |
| ------------ | -------------------------------------------- |
| SnowBall     | `0x02836df426F73142A9860578Bc9E0aAbcB2AEef8` |
| BurnDividend | `0xB2414df84a9551B374D0d2f5B76f242ca911BEAE` |
| Gift         | `0xcDE778F62D40d40fd61b51f07714BD9f52F438E6` |
| Split        | `0x3830723F569cF9f36B25c291367eD1ddB4Ac76F7` |

### `marketVaultData` Encoding

| Vault Type   | Encoding                             | Example                                             |
| ------------ | ------------------------------------ | --------------------------------------------------- |
| SnowBall     | `abi.encode(address keeper)`         | Fixed: `0xdD90b6E098E0c0756721D2bec83fDbDA14bB6eF9` |
| BurnDividend | `abi.encode(address keeper)`         | Fixed: `0xdD90b6E098E0c0756721D2bec83fDbDA14bB6eF9` |
| Gift         | `abi.encode(string xHandle)`         | X (Twitter) handle of gift recipient                |
| Split        | `abi.encode(Recipient[] recipients)` | Array of `{ address, uint16 bps }`, bps sum = 10000 |

Discover the deployed vault address from the `MarketVaultCreated` event:

```solidity
event MarketVaultCreated(
    address indexed token,
    address indexed vaultFactory,
    address vault,
    bytes marketVaultData
);
```

For detailed `marketVaultData` encoding examples, see [Creating a Coin](/for-developers/creating-a-coin.md#creating-a-tax-token-with-vault).