# Market Vault

**Purpose:** User position storage and tracking. Uses bitmasks to track collateral (bits 0-63) and debt (bits 64-127) in a single uint.

## List of Core Functions

Configuration:

* set-impl: Update implementation contract (7-day timelock)
* set-pause-states: Pause/unpause operations
* get-impl: Get current implementation
* get-pause-states: Get pause configuration

Position Queries:

* get-nr: Get position counter (nonce)
* lookup: Get position data by ID
* resolve: Get position ID for account
* resolve-safe: Safe resolve with error handling
* get-position: Get complete position with collateral & debt lists

Collateral Queries:

* get-collateral: Get collateral amount for specific asset
* lookup-collateral: Get all collateral for position
* get-account-scaled-debt: Get scaled debt for account (legacy)

Debt Queries:

* get-debt: Get debt amount for specific asset
* debt-scaled: Get scaled debt for specific asset
* lookup-debt: Get all debt for position

Position Mutations (Market Auth Only):

* collateral-add: Add collateral to position
* collateral-remove: Remove collateral from position
* debt-add-scaled: Add scaled debt to position
* debt-remove-scaled: Remove scaled debt from position

***

## Function Parameters

### set-impl

Update implementation contract. Requires DAO authorization.

| Parameter | Type      | Description                         |
| --------- | --------- | ----------------------------------- |
| new       | principal | New implementation contract address |

Returns: `(response bool uint)` - Success or error

Authorization: DAO executor only

Note: Implementation changes subject to 7-day timelock in dao-multisig

***

### set-pause-states

Configure pause states for operations.

| Parameter | Type                                                                                 | Description                                 |
| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------- |
| states    | `{collateral-add: bool, collateral-remove: bool, debt-add: bool, debt-remove: bool}` | Pause configuration for each operation type |

Returns: `(response bool uint)` - Success or error

Authorization: DAO executor only

***

### get-impl

Get current implementation contract.

| Parameter | Type | Description   |
| --------- | ---- | ------------- |
| (none)    | -    | No parameters |

Returns: `(optional principal)` - Implementation address or none

***

### get-pause-states

Get current pause configuration.

| Parameter | Type | Description   |
| --------- | ---- | ------------- |
| (none)    | -    | No parameters |

Returns: `(response {...} uint)` - Pause states or error

Fields:

* `collateral-add`: bool
* `collateral-remove`: bool
* `debt-add`: bool
* `debt-remove`: bool

***

### get-nr

Get position counter (next position ID).

| Parameter | Type | Description   |
| --------- | ---- | ------------- |
| (none)    | -    | No parameters |

Returns: `uint` - Next position ID

***

### lookup

Get position data by position ID.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| id        | uint | Position ID |

Returns: `(optional {...})` - Position data or none

Fields:

* `account`: principal - Position owner
* `coll-debt-mask`: uint - Bitmask (collateral in bits 0-63, debt in bits 64-127)
* `last-borrow-time`: uint - Last borrow timestamp (for liquidation protection)

***

### resolve

Get position ID for account. Creates new position if none exists.

| Parameter | Type      | Description     |
| --------- | --------- | --------------- |
| account   | principal | Account address |

Returns: `uint` - Position ID

Note: Creates new position entry if account has no position yet

***

### resolve-safe

Safe resolve with error handling instead of auto-creation.

| Parameter | Type      | Description     |
| --------- | --------- | --------------- |
| account   | principal | Account address |

Returns: `(response uint uint)` - Position ID or error if not found

***

### get-collateral

Get collateral amount for specific asset.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| id        | uint | Position ID |
| asset     | uint | Asset ID    |

Returns: `uint` - Collateral amount (0 if none)

***

### lookup-collateral

Get all collateral for position matching mask.

| Parameter    | Type | Description                                          |
| ------------ | ---- | ---------------------------------------------------- |
| id           | uint | Position ID                                          |
| mask         | uint | Asset mask to query (filters which assets to return) |
| enabled-mask | uint | Enabled assets mask from registry                    |

Returns: `(list 64 { aid: uint, amount: uint })` - List of collateral entries

***

### get-account-scaled-debt

Get scaled debt for account. Legacy function.

| Parameter | Type      | Description     |
| --------- | --------- | --------------- |
| account   | principal | Account address |
| asset-id  | uint      | Asset ID        |

Returns: `uint` - Scaled debt amount

***

### get-debt

Get actual debt amount for specific asset (includes accrued interest).

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| id        | uint | Position ID |
| asset     | uint | Asset ID    |

Returns: `uint` - Debt amount (0 if none)

Note: Converts scaled debt to actual debt using current index

***

### debt-scaled

Get scaled debt for specific asset (before interest accrual).

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| id        | uint | Position ID |
| asset     | uint | Asset ID    |

Returns: `uint` - Scaled debt amount

***

### lookup-debt

Get all debt for position matching mask.

| Parameter    | Type | Description                       |
| ------------ | ---- | --------------------------------- |
| id           | uint | Position ID                       |
| mask         | uint | Asset mask to query               |
| enabled-mask | uint | Enabled assets mask from registry |

Returns: `(list 64 { aid: uint, scaled: uint })` - List of debt entries (scaled)

***

### get-position

Get complete position with collateral and debt lists.

| Parameter    | Type      | Description                       |
| ------------ | --------- | --------------------------------- |
| account      | principal | Account address                   |
| enabled-mask | uint      | Enabled assets mask from registry |

Returns: `{ collateral: (list 64 {...}), debt: (list 64 {...}) }` - Complete position data

Note: Returns empty lists if position doesn't exist

***

### collateral-add

Add collateral to position. Market authorization required.

| Parameter | Type         | Description          |
| --------- | ------------ | -------------------- |
| account   | principal    | Position owner       |
| amount    | uint         | Amount to add        |
| ft        | `<ft-trait>` | Asset token contract |
| asset-id  | uint         | Asset ID             |

Returns: `(response uint uint)` - Updated collateral amount or error

Authorization: Market implementation only (contract-caller check)

Note: Transfers tokens from account to market-vault

***

### collateral-remove

Remove collateral from position. Market authorization required.

| Parameter | Type         | Description               |
| --------- | ------------ | ------------------------- |
| account   | principal    | Position owner            |
| amount    | uint         | Amount to remove          |
| ft        | `<ft-trait>` | Asset token contract      |
| asset-id  | uint         | Asset ID                  |
| recipient | principal    | Address to receive tokens |

Returns: `(response uint uint)` - Remaining collateral amount or error

Authorization: Market implementation only (contract-caller check)

Note: Transfers tokens from market-vault to recipient

***

### debt-add-scaled

Add scaled debt to position. Market authorization required.

| Parameter     | Type      | Description          |
| ------------- | --------- | -------------------- |
| account       | principal | Position owner       |
| scaled-amount | uint      | Scaled amount to add |
| asset-id      | uint      | Asset ID             |

Returns: `(response uint uint)` - Updated scaled debt or error

Authorization: Market implementation only (contract-caller check)

Note: Updates last-borrow-time to prevent same-block liquidation

***

### debt-remove-scaled

Remove scaled debt from position. Market authorization required.

| Parameter     | Type      | Description             |
| ------------- | --------- | ----------------------- |
| account       | principal | Position owner          |
| scaled-amount | uint      | Scaled amount to remove |
| asset-id      | uint      | Asset ID                |

Returns: `(response uint uint)` - Remaining scaled debt or error

Authorization: Market implementation only (contract-caller check)

Note: Clears debt bit in mask if debt reaches zero


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zestprotocol.com/start/stacks-market-v2-smart-contracts-overview/v2-contracts/market-contracts/market-vault.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.