> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/developers/wealth/vault-lifecycle.md).

# Vault Lifecycle

State machines for `escrow_vault` deposits and redemptions. Executable steps are on the how-to pages below. Load vault addresses from [Fund Information](/documentation/for-developers/api-reference/wealth-api/funds.md#get-fund-information). Encode the referral before the request ([Referrals](/documentation/for-developers/developers/wealth/referrals.md)).

This page does not apply to SoDEX RWA tokens (`clob`). A submitted request does not mint shares or return assets in the same transaction. Claim only when [User Fund History](/documentation/for-developers/api-reference/wealth-api/user-fund-history.md) and the on-chain request show the result was not automatically delivered.

## Deposit

```mermaid
flowchart TD
  A["Confirm escrow_vault, status and not paused"] --> B["Underlying on ValueChain; encode referral"]
  B --> C{"Submit how"}
  C -->|Direct| D["Approve asset; requestDeposit"]
  C -->|Signed| E["Sign RequestDeposit; Relayer may submit OnBehalf"]
  D --> F["Save request tx hash"]
  E --> F
  F --> G["Wait for settlement"]
  G --> H{"Shares auto-delivered?"}
  H -->|Yes| J["Verify receiver vault-share balance"]
  H -->|No| I["claimDeposit"]
  I --> J
```

Credit is the vault ERC-20 share balance on ValueChain, not Spot or Perps. `assets` must meet `getMinDepositAmount()`. Direct submission needs an underlying-asset approval and SOSO for gas. A signed `OnBehalf` call can be broadcast by the [Transaction Relayer](/documentation/for-developers/developers/valuechain-evm/relayer.md).

1. Confirm the fund is `escrow_vault`, is accepting deposits, and `chainConfig.paused` is not true. The underlying must already be on ValueChain.
2. Encode `referral` (use `bytes32(0)` when none applies). Submit `requestDeposit(assets, receiver, referral)` or a signed `requestDepositOnBehalf`. Save the transaction hash.
3. Wait for settlement. Match history to that hash. If shares were not auto-delivered, call `claimDeposit(receiver, requestId)`.
4. Verify the receiver's vault share balance before treating the deposit as complete.

## Redeem

```mermaid
flowchart TD
  A["Confirm vault shares and min redeem"] --> B["Encode referral"]
  B --> C{"Submit how"}
  C -->|Direct| D["requestRedeem"]
  C -->|Signed| E["Sign RequestRedeem; Relayer may submit OnBehalf"]
  D --> F["Save request tx hash"]
  E --> F
  F --> G["Wait for settlement"]
  G --> H["Immediate assets: auto-delivery or claimRedeem"]
  G --> I{"Delayed assets?"}
  I -->|Yes| J["Wait for delayed settlement"]
  J --> K["Auto-delivery or claimDelayedRedeem"]
  I -->|No| L["No delayed leg"]
  H --> M["Reconcile underlying for every applicable leg"]
  K --> M
  L --> M
```

The request spends **vault shares** the user already holds. No underlying-asset approval is required. `shares` must meet `getMinRedeemShares()`. Credit is the underlying asset on ValueChain. An immediate leg completing does not finish a delayed leg.

1. Encode `referral` and submit `requestRedeem(shares, receiver, referral)` or a signed `requestRedeemOnBehalf`. Save the transaction hash.
2. Wait for settlement. For the non-delayed portion, confirm auto-delivery or call `claimRedeem(receiver, requestId)`.
3. If a delayed portion exists, wait for that batch, then confirm auto-delivery or call `claimDelayedRedeem(receiver, requestId)`.
4. Reconcile the underlying balance for every applicable leg before treating the redemption as complete.

## Settlement and Claims

Query [User Fund History](/documentation/for-developers/api-reference/wealth-api/user-fund-history.md) with the owner address and fund ID. Match the original transaction hash and operation kind; retain `entryId` when present. Do not select a request solely by its position in the timeline or by a pre-submission next-ID query.

| Entry condition       | Integration action                                                                                                               |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| No matching entry     | Continue querying with bounded backoff; indexing may lag. Do not submit another deposit or redemption.                           |
| `claimable=true`      | Confirm the matching on-chain request and simulate the applicable claim before submitting.                                       |
| `delayedPending=true` | Keep tracking the delayed leg, even if an immediate claim is available or has completed.                                         |
| `claimable=false`     | Do not submit a claim based on this response. Check balances to distinguish pending settlement from an already delivered result. |
| Either flag omitted   | Treat that aspect as unknown; do not substitute false.                                                                           |

For a deposit, the claim method is `claimDeposit`. For a redemption, distinguish `claimRedeem` from `claimDelayedRedeem` using the on-chain request. The aggregate `claimable` flag does not select the redemption leg. If settlement auto-delivered shares or assets, skip the corresponding claim.

Scripts and claim calls are on [Settlement and Claims](/documentation/for-developers/developers/wealth/vault-lifecycle/settlement-and-claims.md).

## How-tos

Direct submission: the user wallet pays ValueChain gas. Signed submission: the user signs; the [Transaction Relayer](/documentation/for-developers/developers/valuechain-evm/relayer.md) can broadcast `OnBehalf`.

{% content-ref url="/pages/YJj0yhyNUfGzvVax9Au7" %}
[Direct Deposits](/documentation/for-developers/developers/wealth/vault-lifecycle/direct-deposits.md)
{% endcontent-ref %}

{% content-ref url="/pages/2cTpaiOb6PElB7vmrlsr" %}
[Direct Redemptions](/documentation/for-developers/developers/wealth/vault-lifecycle/direct-redemptions.md)
{% endcontent-ref %}

{% content-ref url="/pages/uzIaEl6IPwoLbrlbryJq" %}
[Signed Deposits](/documentation/for-developers/developers/wealth/vault-lifecycle/signed-deposits.md)
{% endcontent-ref %}

{% content-ref url="/pages/PTKwTmBlXRxFsAhsjXSY" %}
[Signed Redemptions](/documentation/for-developers/developers/wealth/vault-lifecycle/signed-redemptions.md)
{% endcontent-ref %}

{% content-ref url="/pages/Y6UGtOgpGCVoTe1N27nr" %}
[Settlement and Claims](/documentation/for-developers/developers/wealth/vault-lifecycle/settlement-and-claims.md)
{% endcontent-ref %}