> For the complete documentation index, see [llms.txt](https://docs.ducatprotocol.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ducatprotocol.com/how-ducat-works/vault-state.md).

# Vault State

A vault is represented by a BTC transaction output, its spending conditions and the protocol history that leads to it. Updating a vault spends its current UTXO and creates a successor output. Closing it ends that chain.

The current transaction flows do not require a separately issued, wallet-held "Vault Token" to represent ownership. Control comes from the keys committed in the vault script; the validator reconstructs the associated record.

### Stored data

| Location                       | Information                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Vault output value             | Gross BTC collateral, in satoshis.                                                                                  |
| Taproot spending conditions    | User and guardian keys, and any oracle threshold hashes.                                                            |
| Vault `OP_RETURN` metadata     | Vault format version, guardian indices and, when debt exists, debt balance, price timestamp and oracle commitments. |
| Each oracle commitment         | Oracle index, base BTC/USD price, threshold price, HASH160 threshold hash and BIP-340 Schnorr signature.            |
| Transaction inputs and history | Which earlier vault and issuance or burn outputs are spent, and how the action relates to prior state.              |
| Protocol profile               | The recognised assets, authorised keys and terms used to interpret the action.                                      |

A debt-free vault uses the **Cleared** metadata form. A vault with debt uses the **Encumbered** form, which contains one to three oracle commitments. The vault format version is not a substitute for identifying the applicable protocol contract.

### Calculated data

The collateralisation ratio is calculated; it is not a percentage stored directly in `OP_RETURN`.

For the documented ratio policy:

```
net_collateral_sats = gross_vault_sats - required_vault_minimum_sats
collateral_ratio = (net_collateral_sats / 100,000,000 × BTC_USD_price) / UNIT_debt
```

UNIT debt is denominated at its USD target for this calculation. UNIT's market exchange price is a separate input to a user's purchase cost or liquidation profit.

With several authenticated oracle commitments, the implementation uses the minimum retained base price for the base-price ratio calculation. Each commitment still has its own threshold and hash.

A display using a fresh market price is different from the ratio derived from the vault's recorded commitments. Interfaces should identify the price and time used. A debt-free vault has no debt ratio; it should be shown as debt-free rather than as an ordinary finite percentage.

### Confirmed state and pending requests

A submitted or signed request is not confirmed Bitcoin state. Track transaction status and reconstruct state from the accepted chain, including changes caused by reorganisations.

For the supported user actions, see [Vaults](https://docs.ducatprotocol.com/how-ducat-works/vaults.md).
