# Smart Contract Integrations

{% hint style="info" %}
You can find the deployed contract addresses here: [Contracts](https://docs.perennial.finance/protocol-info/protocol-contracts) 
{% endhint %}

The following actions are useful when directly interacting with the markets. To make life easier, Perennial has built an [Operator](https://docs.perennial.finance/before-integrating#operators) contract called: `MultiInvoker` which can be used to simplify/abstract much of this flow. See more about it [here](https://docs.perennial.finance/building-on-perennial/frontend-and-client-integrations)

## Market Operations (Market.sol)

The following are common actions you might need to undertake to interact with an instance of a market contract. 

Source code: [here](https://github.com/equilibria-xyz/perennial-v2/blob/main/packages/perennial/contracts/Market.sol)

### Get a Market's Global Position

When interacting with a given market its useful to know the overall state. In order to find this you should call two functions: `position()` & `global()`. With these you can calculate things like open interest, skew, funding rate, interest rate etc.

* Call `position()`
  * Returns
    * `timestamp` - The timestamp of the position
    * `maker` - The maker position size\*
    * `long` - The long position size\*
    * `short` - The short position size\*
    * Notes
      * \* -  This is the **aggregate** value of all positions denominated in units of the [Payoff](https://docs.perennial.finance/protocol/markets/payoff-and-positions) function
* Call `global()` 
  * Returns:
    * `pAccumulator` - The current PAccumulator state
    * `latestPrice` - The latest valid price

Helpful calculations:

* $$openInterestInUSD = (long + short) \* latestPrice$$
* $$marketSkew = long / short$$
* [Funding Rate](https://github.com/equilibria-xyz/perennial-interface-v2/blob/efc873819cc809c56010dc2feb7aff57cbb4e695/src/utils/fundingAndInterestUtils.ts#L38) - using `pAccumulator` 
* [Interest Rate](https://github.com/equilibria-xyz/perennial-interface-v2/blob/efc873819cc809c56010dc2feb7aff57cbb4e695/src/utils/fundingAndInterestUtils.ts#L8) - using `long` , `short` & `maker`

### Get an Account's Market Position

In order to read a particular account's position you can use the `positions()` function. This returns a similar object to the global `position()` call. 

* Call `positions(address)`
  * Returns
    * `timestamp` - The timestamp of the position
    * `maker` - The maker position size\*
    * `long` - The long position size\*
    * `short` - The short position size\*
    * `fee` - The fee for the position^
    * `keeper` - The fixed settlement fee for the position^
    * `collateral` - The collateral at the time of the position settlement^
    * `delta` - The change in collateral during this position^
  * Notes
    * \* The value of the position denominated in units of the [Payoff](https://docs.perennial.finance/protocol/markets/payoff-and-positions) function
    * ^ Only used for pending positions

### Update Your Position (Make a Trade)

In each Market, there is an `update()` function which a user calls to modify their position. You can go long, short, make a market, deposit or withdraw collateral using this command. 

* `Approve()` DSU (collateral) on specific market
* Call `update()`
  * Arguments:
    * `account` - The account to operate on 
    * `newMaker` - The new maker position for the account\*
    * `newLong` - The new long position for the account\*
    * `newShort` - The new short position for the account\*
    * `collateral` - The collateral amount to add or remove from the account^
    * `protect` - Whether to put the account into a protected status for liquidations
  * Notes:
    * \* This is the **absolute** value of the position denominated in units of the [Payoff](https://docs.perennial.finance/protocol/markets/payoff-and-positions) function.
    * ^ Positive number to add collateral, negative to remove.

### Calculating Available Liquidity:

When opening/closing a position the market is bound by available liquidity being provided by the Makers. In order to calculate this you can do the following:

* Call `position()`
  * Returns
    * `timestamp` - The timestamp of the position
    * `maker` - The maker position size\*
    * `long` - The long position size\*
    * `short` - The short position size\*
  * Notes
    * \* -  This is the **aggregate** value of all positions denominated in units of the [Payoff](https://docs.perennial.finance/protocol/markets/payoff-and-positions) function
* Calculate Liquidity in USD
  * $$\begin{align\*}   liqMajor &= maker + \min(long, short) - \max(long, short) \  liqMinor &= liqMajor + maker  \end{align\*}$$ 
    * *Note: availableMajor equal whichever side has more open interest*
* Call `global()` 
  * Returns:
    * `latestPrice` - The latest valid price
* Calculate Liquidity in units of Payoff 
  * $$liqUnits = liqMajor / latestPrice$$

### Confirming Position Update

Due to the delayed settlement flow of Perennial, while position updates are very likely to be settled there are rare cases where settlement might not occur. To check your position has been updated you can do the following:

* `Updated(account, context.currentTimestamp, ...)` is emitted when you submit an `updated()`.
* Call `Market.versions(timestamp)` using the timestamp from the event.
  * Returns a struct with the property `valid`. If the value is `true` then your update was successful.
  * If the value is `false`, you can check to see if the `timestamp` from the `Update()` event is after the `timestamp` returned in the `latest()` call in Market's Oracle. If this is the case, the `update()` has failed and needs to be resubmitted. 

## Example Contract Integration: Vaults

The multi-market maker vault that is featured on the Perennial UI is a great example of a contract integration into the Perennial market contracts. 

The vault is a standalone contract that acts as a normal user on configured markets. Whenever a user deposits into/withdraws from the vault contract it update the maker positions across the markets. 

See the codebase [here](https://github.com/equilibria-xyz/perennial-v2/blob/main/packages/perennial-vault/contracts/Vault.sol)

{% hint style="warning" %}
Make sure to check out the [Considerations](https://docs.perennial.finance/building-on-perennial/before-integrating) section before building a direct integration!
{% endhint %}