# Swivel

## Swivel

### Contents

### Globals

> Note this list contains both internal and external attributes

| Var               | Type                                            |
| ----------------- | ----------------------------------------------- |
| cancelled         | mapping(bytes32 => bool)                        |
| filled            | mapping(bytes32 => uint256)                     |
| withdrawals       | mapping(address => uint256)                     |
| approvals         | mapping(address => mapping(address => uint256)) |
| NAME              | string                                          |
| VERSION           | string                                          |
| HOLD              | uint256                                         |
| feeChange         | uint256                                         |
| domain            | bytes32                                         |
| marketPlace       | address                                         |
| admin             | address                                         |
| aaveAddr          | address                                         |
| MIN\_FEENOMINATOR | uint16                                          |
| feenominators     | uint16\[4]                                      |

### Modifiers

#### authorized

Restricts `msg.sender` as the only viable caller of a method

**Declaration**

```solidity
modifier authorized
```

### Functions

#### constructor

**Declaration**

```solidity
function constructor(
address m,
address a
) public
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                                    |
| --- | ------- | -------------------------------------------------------------- |
| `m` | address | Deployed MarketPlace contract address                          |
| `a` | address | Address of a deployed Aave contract implementing our interface |

#### initiate

Allows a user to initiate a position

**Declaration**

```solidity
function initiate(
struct Hash.Order[] o,
uint256[] a,
struct Sig.Components[] c
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                     | Description                                                         |
| --- | ------------------------ | ------------------------------------------------------------------- |
| `o` | struct Hash.Order\[]     | Array of offline Swivel.Orders                                      |
| `a` | uint256\[]               | Array of order volume (principal) amounts relative to passed orders |
| `c` | struct Sig.Components\[] | Array of Components from valid ECDSA signatures                     |

#### initiateVaultFillingZcTokenInitiate

Allows a user to initiate a Vault by filling an offline zcToken initiate order

> This method should pass (underlying, maturity, maker, sender, principalFilled) to MarketPlace.custodialInitiate

**Declaration**

```solidity
function initiateVaultFillingZcTokenInitiate(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                     |
| --- | --------------------- | --------------------------------------------------------------- |
| `o` | struct Hash.Order     | Order being filled                                              |
| `a` | uint256               | Amount of volume (premium) being filled by the taker's initiate |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                           |

#### initiateZcTokenFillingVaultInitiate

Allows a user to initiate a zcToken by filling an offline vault initiate order

> This method should pass (underlying, maturity, sender, maker, a) to MarketPlace.custodialInitiate

**Declaration**

```solidity
function initiateZcTokenFillingVaultInitiate(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                       |
| --- | --------------------- | ----------------------------------------------------------------- |
| `o` | struct Hash.Order     | Order being filled                                                |
| `a` | uint256               | Amount of volume (principal) being filled by the taker's initiate |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                             |

#### initiateZcTokenFillingZcTokenExit

Allows a user to initiate zcToken? by filling an offline zcToken exit order

> This method should pass (underlying, maturity, maker, sender, a) to MarketPlace.p2pZcTokenExchange

**Declaration**

```solidity
function initiateZcTokenFillingZcTokenExit(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                       |
| --- | --------------------- | ----------------------------------------------------------------- |
| `o` | struct Hash.Order     | Order being filled                                                |
| `a` | uint256               | Amount of volume (principal) being filled by the taker's initiate |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                             |

#### initiateVaultFillingVaultExit

Allows a user to initiate a Vault by filling an offline vault exit order

> This method should pass (underlying, maturity, maker, sender, principalFilled) to MarketPlace.p2pVaultExchange

**Declaration**

```solidity
function initiateVaultFillingVaultExit(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                  |
| --- | --------------------- | ------------------------------------------------------------ |
| `o` | struct Hash.Order     | Order being filled                                           |
| `a` | uint256               | Amount of volume (interest) being filled by the taker's exit |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                        |

#### exit

Allows a user to exit (sell) a currently held position to the marketplace.

**Declaration**

```solidity
function exit(
struct Hash.Order[] o,
uint256[] a,
struct Sig.Components[] c
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                     | Description                                                         |
| --- | ------------------------ | ------------------------------------------------------------------- |
| `o` | struct Hash.Order\[]     | Array of offline Swivel.Orders                                      |
| `a` | uint256\[]               | Array of order volume (principal) amounts relative to passed orders |
| `c` | struct Sig.Components\[] | Components of a valid ECDSA signature                               |

#### exitZcTokenFillingZcTokenInitiate

Allows a user to exit their zcTokens by filling an offline zcToken initiate order

> This method should pass (underlying, maturity, sender, maker, principalFilled) to MarketPlace.p2pZcTokenExchange

**Declaration**

```solidity
function exitZcTokenFillingZcTokenInitiate(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                  |
| --- | --------------------- | ------------------------------------------------------------ |
| `o` | struct Hash.Order     | Order being filled                                           |
| `a` | uint256               | Amount of volume (interest) being filled by the taker's exit |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                        |

#### exitVaultFillingVaultInitiate

Allows a user to exit their Vault by filling an offline vault initiate order

> This method should pass (underlying, maturity, sender, maker, a) to MarketPlace.p2pVaultExchange

**Declaration**

```solidity
function exitVaultFillingVaultInitiate(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                   |
| --- | --------------------- | ------------------------------------------------------------- |
| `o` | struct Hash.Order     | Order being filled                                            |
| `a` | uint256               | Amount of volume (principal) being filled by the taker's exit |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                         |

#### exitVaultFillingZcTokenExit

Allows a user to exit their Vault filling an offline zcToken exit order

> This method should pass (underlying, maturity, maker, sender, a) to MarketPlace.exitFillingExit

**Declaration**

```solidity
function exitVaultFillingZcTokenExit(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                   |
| --- | --------------------- | ------------------------------------------------------------- |
| `o` | struct Hash.Order     | Order being filled                                            |
| `a` | uint256               | Amount of volume (principal) being filled by the taker's exit |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                         |

#### exitZcTokenFillingVaultExit

Allows a user to exit their zcTokens by filling an offline vault exit order

> This method should pass (underlying, maturity, sender, maker, principalFilled) to MarketPlace.exitFillingExit

**Declaration**

```solidity
function exitZcTokenFillingVaultExit(
struct Hash.Order o,
uint256 a,
struct Sig.Components c
) internal
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                                                  |
| --- | --------------------- | ------------------------------------------------------------ |
| `o` | struct Hash.Order     | Order being filled                                           |
| `a` | uint256               | Amount of volume (interest) being filled by the taker's exit |
| `c` | struct Sig.Components | Components of a valid ECDSA signature                        |

#### cancel

Allows a user to cancel an order, preventing it from being filled in the future

**Declaration**

```solidity
function cancel(
struct Hash.Order[] o
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                 | Description                             |
| --- | -------------------- | --------------------------------------- |
| `o` | struct Hash.Order\[] | Array of offline orders being cancelled |

#### setAdmin

Sets the admin

**Declaration**

```solidity
function setAdmin(
address a
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description            |
| --- | ------- | ---------------------- |
| `a` | address | Address of a new admin |

#### scheduleWithdrawal

Allows the admin to schedule the withdrawal of tokens

**Declaration**

```solidity
function scheduleWithdrawal(
address e
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                          |
| --- | ------- | ------------------------------------ |
| `e` | address | Address of (ERC20) token to withdraw |

#### scheduleApproval

Allows the admin to schedule the approval of tokens

**Declaration**

```solidity
function scheduleApproval(
address e,
address a
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                         |
| --- | ------- | ----------------------------------- |
| `e` | address | Address of (ERC20) token to approve |
| `a` | address | Address of the contract to approve  |

#### scheduleFeeChange

allows the admin to schedule a change to the fee denominators

**Declaration**

```solidity
function scheduleFeeChange(
uint16[4] f
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type       | Description                                                                                                  |
| --- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `f` | uint16\[4] | array of length 4 holding values which suggest replacing any at the same index for the current feenominators |

#### blockWithdrawal

Emergency function to block unplanned withdrawals

**Declaration**

```solidity
function blockWithdrawal(
address e
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                          |
| --- | ------- | ------------------------------------ |
| `e` | address | Address of token withdrawal to block |

#### blockApproval

Emergency function to block unplanned approvals

**Declaration**

```solidity
function blockApproval(
address e,
address a
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                                  |
| --- | ------- | -------------------------------------------- |
| `e` | address | Address of token approval to block           |
| `a` | address | Address of the contract to block approval of |

#### blockFeeChange

Emergency function to block unplanned changes to fee structure

**Declaration**

```solidity
function blockFeeChange(
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

#### withdraw

Allows the admin to withdraw the given token, provided the holding period has been observed

**Declaration**

```solidity
function withdraw(
address e
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                  |
| --- | ------- | ---------------------------- |
| `e` | address | Address of token to withdraw |

#### changeFee

allows the admin to set new fee denominators

> note that, since 0 values are allowable the way to leave a feenominator value unchanged is to pass the existing value

**Declaration**

```solidity
function changeFee(
uint16[4] f
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type       | Description                                                                                            |
| --- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `f` | uint16\[4] | array of length 4 holding values which will replace any at the same index in the current feenominators |

#### approveUnderlying

Allows the admin to bulk approve given compounding addresses at the underlying token, saving marginal approvals, providing the holding period has been observed

**Declaration**

```solidity
function approveUnderlying(
address[] u,
address[] c
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type       | Description                         |
| --- | ---------- | ----------------------------------- |
| `u` | address\[] | array of underlying token addresses |
| `c` | address\[] | array of compound token addresses   |

#### splitUnderlying

Allows users to deposit underlying and in the process split it into/mint zcTokens and vault notional. Calls mPlace.mintZcTokenAddingNotional

**Declaration**

```solidity
function splitUnderlying(
uint8 p,
address u,
uint256 m,
uint256 a
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                               |
| --- | ------- | --------------------------------------------------------- |
| `p` | uint8   | Protocol Enum value associated with this market pair      |
| `u` | address | Underlying token address associated with this market pair |
| `m` | uint256 | Maturity timestamp of this associated market              |
| `a` | uint256 | Amount of underlying being deposited                      |

#### combineTokens

Allows users deposit/burn 1-1 amounts of both zcTokens and vault notional, in the process "combining" the two, and redeeming underlying. Calls mPlace.burnZcTokenRemovingNotional.

**Declaration**

```solidity
function combineTokens(
uint8 p,
address u,
uint256 m,
uint256 a
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                          |
| --- | ------- | ---------------------------------------------------- |
| `p` | uint8   | Protocol Enum value associated with this market pair |
| `u` | address | Underlying token address associated with the market  |
| `m` | uint256 | Maturity timestamp of the market                     |
| `a` | uint256 | Amount of zcTokens being redeemed                    |

#### authRedeem

Allows MarketPlace to complete its contractual obligation as IRedeemer, redeeming zcTokens and withdrawing underlying p Protocol Enum value associated with this market pair

> Note that this bubbles up from the zcToken instead of starting on Swivel (as per the ERC5095)

**Declaration**

```solidity
function authRedeem(
uint8 u,
address c,
address t,
address a
) external authorized returns
(bool)
```

**Modifiers:**

| Modifier   |
| ---------- |
| authorized |

**Args:**

| Arg | Type    | Description                                               |
| --- | ------- | --------------------------------------------------------- |
| `u` | uint8   | Underlying token address associated with this market pair |
| `c` | address | Compound token address associated with this market pair   |
| `t` | address | Address of the user receiving the underlying tokens       |
| `a` | address | Amount of underlying being redeemed                       |

#### redeemZcToken

Allows zcToken holders to redeem their tokens for underlying tokens after maturity has been reached (via MarketPlace).

**Declaration**

```solidity
function redeemZcToken(
uint8 p,
address u,
uint256 m,
uint256 a
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                          |
| --- | ------- | ---------------------------------------------------- |
| `p` | uint8   | Protocol Enum value associated with this market pair |
| `u` | address | Underlying token address associated with the market  |
| `m` | uint256 | Maturity timestamp of the market                     |
| `a` | uint256 | Amount of zcTokens being redeemed                    |

#### redeemVaultInterest

Allows Vault owners to redeem any currently accrued interest (via MarketPlace)

**Declaration**

```solidity
function redeemVaultInterest(
uint8 p,
address u,
uint256 m
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                          |
| --- | ------- | ---------------------------------------------------- |
| `p` | uint8   | Protocol Enum value associated with this market pair |
| `u` | address | Underlying token address associated with the market  |
| `m` | uint256 | Maturity timestamp of the market                     |

#### redeemSwivelVaultInterest

Allows Swivel to redeem any currently accrued interest (via MarketPlace)

**Declaration**

```solidity
function redeemSwivelVaultInterest(
uint8 p,
address u,
uint256 m
) external returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                          |
| --- | ------- | ---------------------------------------------------- |
| `p` | uint8   | Protocol Enum value associated with this market pair |
| `u` | address | Underlying token address associated with the market  |
| `m` | uint256 | Maturity timestamp of the market                     |

#### validOrderHash

Verifies the validity of an order and it's signature.

**Declaration**

```solidity
function validOrderHash(
struct Hash.Order o,
struct Sig.Components c
) internal returns
(bytes32)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type                  | Description                           |
| --- | --------------------- | ------------------------------------- |
| `o` | struct Hash.Order     | An offline Swivel.Order               |
| `c` | struct Sig.Components | Components of a valid ECDSA signature |

**Returns:**

| Type  | Description   |
| ----- | ------------- |
| `the` | hashed order. |

#### deposit

Use the Protocol Enum to direct deposit type transactions to their specific library abstraction

> This functionality is an abstraction used by `IVFZI`, `IZFVI` and `splitUnderlying`

**Declaration**

```solidity
function deposit(
uint8 p,
address u,
address c,
uint256 a
) internal returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                       |
| --- | ------- | ------------------------------------------------- |
| `p` | uint8   | Protocol Enum Value                               |
| `u` | address | Address of an underlying token (used by Aave)     |
| `c` | address | Compounding token address                         |
| `a` | uint256 | Amount to deposit todo compounding or underlying? |

#### withdraw

Use the Protocol Enum to direct withdraw type transactions to their specific library abstraction

> This functionality is an abstraction used by `EVFZE`, `EZFVE`, `combineTokens`, `redeemZcToken` and `redeemVaultInterest`. Note that while there is an external method `withdraw` also on this contract the unique method signatures (and visibility) exclude any possible clashing

**Declaration**

```solidity
function withdraw(
uint8 p,
address u,
address c,
uint256 a
) internal returns
(bool)
```

**Modifiers:**

No modifiers

**Args:**

| Arg | Type    | Description                                   |
| --- | ------- | --------------------------------------------- |
| `p` | uint8   | Protocol Enum Value                           |
| `u` | address | Address of an underlying token (used by Aave) |
| `c` | address | Compounding token address                     |
| `a` | uint256 | Amount to withdraw                            |

### Events

#### Cancel

Emitted on order cancellation

#### Initiate

Emitted on any initiate\*

> filled is 'principalFilled' when (vault:false, exit:false) && (vault:true, exit:true) filled is 'premiumFilled' when (vault:true, exit:false) && (vault:false, exit:true)

#### Exit

Emitted on any exit\*

> filled is 'principalFilled' when (vault:false, exit:false) && (vault:true, exit:true) filled is 'premiumFilled' when (vault:true, exit:false) && (vault:false, exit:true)

#### ScheduleWithdrawal

Emitted on token withdrawal scheduling

#### ScheduleApproval

Emitted on token approval scheduling

#### ScheduleFeeChange

Emitted on fee change scheduling

#### BlockWithdrawal

Emitted on token withdrawal blocking

#### BlockApproval

Emitted on token approval blocking

#### BlockFeeChange

Emitted on fee change blocking

#### ChangeFee

Emitted on a change to the fee structure

#### SetAdmin

Emitted on a change of the admin


---

# 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.swivel.finance/swivel-v3.0.0/developers/contract/contracts/swivel.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.