> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/vault.md).

# Vault Examples

Token vault mechanics example - understand v2 vault operations for custody and fee management

Token vault is used to store referral fees on a separate contract similar to lp account. This will allow us to decrease tx fees for swaps since users won't have to pay for additional jetton transfer tx.

Vault address is defined by `router_address`, `owner_address` and `router_token_Wallet_address`, so for each token each user can have a dedicated vault contract.

## Swap diagram with referral

`Bob` is user doing the swap, `Alice` is referrer, `Send` is send token, `Receive` is receive token.

```mermaid
flowchart LR
	A0(("Bob"))
	A1["Bob<br/>Send<br/>Wallet"]
	A2["Router<br/>Send<br/>Wallet"]
	A3{"Router"}
	A4(["Pool<br/>Send-Receive"])
	A5>"Alice<br/>Receive<br/>Vault"]
	A6["Router<br/>Receive<br/>Wallet"]
	A7["Bob<br/>Receive<br/>Wallet"]

	A0 --> |index: 0<br/>op::transfer|A1
	A1 --> |index: 1<br/>op::internal_transfer|A2
	A2 --> |index: 2<br/>op::transfer_notification|A3
	A2 -.-> |index: 3<br/>op::excesses|A0
	A3 --> |index: 4<br/>op::swap|A4
	A4 -.-> |index: 5<br/>op::pay_vault|A3
	A4 -.-> |index: 6<br/>op::pay_to|A3
	A3 --> |index: 7<br/>op::deposit_ref_fee|A5
	A3 --> |index: 8<br/>op::transfer|A6
	A5 -.-> |index: 9<br/>op::excesses|A0
	A6 --> |index: 10<br/>op::internal_transfer|A7
	A7 -.-> |index: 11<br/>op::excesses|A0

	linkStyle 0 stroke:#ff4747,color:#ff4747
	linkStyle 1 stroke:#ff4747,color:#ff4747
	linkStyle 2 stroke:#ff4747,color:#ff4747
	linkStyle 3 stroke:#0400f0,color:#0400f0
	linkStyle 4 stroke:#ff4747,color:#ff4747
	linkStyle 5 stroke:#02dbdb,color:#02dbdb
	linkStyle 6 stroke:#02dbdb,color:#02dbdb
	linkStyle 7 stroke:#ff4747,color:#ff4747
	linkStyle 8 stroke:#ff4747,color:#ff4747
	linkStyle 9 stroke:#0400f0,color:#0400f0
	linkStyle 10 stroke:#ff4747,color:#ff4747
	linkStyle 11 stroke:#0400f0,color:#0400f0

```

## Withdraw from vault

Withdraw op can be called by anyone, not only the `Vault` owner. All excesses are sent to the owner.

```mermaid
flowchart LR
	A0(("Bob"))
	A1>"Alice<br/>Receive<br/>Vault"]
	A2{"Router"}
	A3["Router<br/>Receive<br/>Wallet"]
	A4["Alice<br/>Receive<br/>Wallet"]
	A5(("Alice"))

	A0 --> |index: 0<br/>op::withdraw_fee|A1
	A1 --> |index: 1<br/>op::vault_pay_to|A2
	A2 --> |index: 2<br/>op::transfer|A3
	A3 --> |index: 3<br/>op::internal_transfer|A4
	A4 --> |index: 4<br/>op::excesses|A5

	linkStyle 0 stroke:#ff4747,color:#ff4747
	linkStyle 1 stroke:#ff4747,color:#ff4747
	linkStyle 2 stroke:#ff4747,color:#ff4747
	linkStyle 3 stroke:#ff4747,color:#ff4747
	linkStyle 4 stroke:#0400f0,color:#0400f0

```

**Notes:**

* the `Vault` contract is deleted on withdraw in order to not pay storage fees (each deposit sends state init so it will be redeployed as soon as any new deposit occurs)

For broader details on collecting referral fees, see the [Omniston referral fees guide](/developer-section/omniston/referral-fees.md#referral-fees-with-dex-v2) (note: while the guide is Omniston-centric, the specified section covers DEX V2 referral mechanics thoroughly).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/vault.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.