> For the complete documentation index, see [llms.txt](https://docs.zestprotocol.com/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zestprotocol.com/start/stacks-market-smart-contracts/v2-contracts/market-contracts/market-vault.md).

# 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