💻PRINT3R Contracts: V1

In depth explanations for each core smart contract within the PRINT3R V1 ecosystem.

Contract Addresses

Stay tuned...

Contract Overview

Glossary

Keeper = Automated operators who keep the platform running smoothly. They are responsible for executing transaction requests, maintaining accurate asset pricing by setting it according to reference exchanges' API values

BRRR = native LP token of the PRINT3R ecosystem. Find out more here.

WETH = Wrapped Ethereum. An ERC20 standardized version of Ether, minted by exchanging it 1:1 with actual Ether.

Front-Running = Executing transactions on a blockchain or in a trading system ahead of a known pending transaction, with the intention of capitalizing on price changes that are anticipated to occur as a result of the pending transaction's execution.

Chainlink = A decentralized oracle network enabling blockchains to securely connect with external data sources.

Vault

The Vault contract stores deposits and handles the main trading functions.

• Deposits: Funds are deposited into the Vault through the minting of BRRR tokens. e.g. if the price of BRRR is $1.50, a user can mint 1 BRRR by depositing 1.50 USDC tokens.

• Withdrawals: Funds can be withdrawn from the vault through the burning of BRRR tokens. e.g. if the price of BRRR is $1.50, a user can burn 1 BRRR to redeem 1.50 USDC tokens.

• Swaps: The vault allows swapping of the tokens held in the vault. e.g. if the price of ETH is $5000 a user can swap 1 ETH for 5000 USDC through the swap function of the vault.

• Longing: Users can open a long position using the vault. e.g. to open a long, a user can deposit 1 ETH into the vault and open a position of $25,000, if the price of ETH at the time of opening the position is $5000, then this would be a 5x long position. If the price of ETH increases by 10%, the user would make a profit of $25,000 * 10% = $2500. A snapshot of the collateral is taken when the position is opened, so in this example, the collateral would be recorded as $5000 and will not change even if the price of ETH changes. To ensure the vault has sufficient funds to pay out any profits, an amount of ETH equivalent to the position’s size is marked as reserved, for this position, 5 ETH in the vault would be reserved.

• Shorting: Users can open a short position using the vault. e.g. to open a short, a user can deposit 5000 USDC into the vault and open a position of $25,000. Stablecoins are required as collateral for shorts and similar to longs, an amount of stablecoins equivalent to the size of the position would be reserved to pay out any profits.

• Liquidations: A position can be liquidated by keepers if the losses of the position reduces the collateral to the point where position size / remaining collateral is more than the max allowed leverage.

Router

The Router contracts provide convenience functions on top of the vault. e.g. the vault requires tokens to be sent to it then the swap function called to execute the swap, the router handles transferring the tokens to the vault as well as wrapping / unwrapping of native tokens if required.

Position Router

The PositionRouter contract handles a two part transaction process for increasing or decreasing long / short positions, this process helps to reduce front-running issues:

1. A user sends the request to increase / decrease a position to the PositionRouter

2. A keeper requests the index price from an aggregate of exchanges

3. The keeper then executes the position at the current index price

4. If the position cannot be executed within the allowed slippage the request is cancelled and the funds are sent back to the user

A user can execute the position on their own if three minutes have passed between the request transaction and the execution transaction. The function of the position keepers is to provide convenience and the protocol can continue to operate even without these keepers.

For swaps, the base fee is 0.25%, while price feeds update within 0.12% price movements, this helps to reduce front-running issues.

Price Feeds

The PriceFeed contract accepts submissions from the price feed keeper(s). Keepers calculate prices using the median price of Binance, Bitfinex and Coinbase. There are two types of keepers:

• Price feed keeper: submits prices routinely for swaps

• Position keeper: submits prices when executing a position

The vault uses the price from the keeper if it is within a configured percentage of the corresponding Chainlink price. If the price exceeds this threshold then a spread would be created between the bounded price and the Chainlink price, this threshold is based on the historical max deviation of the Chainlink price from the median price of reference exchanges. For example, if the max deviation is 2.5% and the price of the token on Chainlink is $100, if the keeper price is $103, then the pricing on the vault would be $100 to $103. When opening a long position, the higher price is used and when closing the lower price is used, for short positions, the lower price is used when opening and the higher price is used for closing.

Prices from the keeper also have an expiry of five minutes, if the last price has been submitted more than five minutes ago, the Chainlink price will be used instead.

For liquidations, these can only occur if the Chainlink price reaches the liquidation price for a position.

Aside from the keeper nodes, watcher nodes are also ran to verify that the prices submitted by the keepers have not been tampered with. Watcher nodes continually compute the median price and compare this with the prices submitted by keepers, if the prices submitted by a keeper does not match the computed median price, then the watcher sends a transaction to enforce a spread between the keeper price and the Chainlink price. For example, if the keeper is operating normally and the Chainlink price is $100 while the keeper price is $101, there would be no spread and $101 would be used for pricing, if the keeper is not operating normally, and the watcher sends a transaction to enforce a spread, then the pricing used would be $100 to $101.

The keepers and watchers are currently run by separate contributors, as we become more certain of the watcher’s reliability, we can open the watcher to be run by any user to receive notifications. Multiple watcher accounts are currently setup to have the ability to send the transaction to enable spreads. It would also be possible to allow more users to send the transaction to enforce a spread by requiring the account to stake or lock a minimum amount of PRINT tokens.

The price feed and position keepers can be further decentralized by using Chainlink keepers or an execution environment such as Intel SGX used by Avalanche.

As of 28 Aug 2022, additional contract level checks have been added. On each fast price update, contract variables store the percentage change in price for the update as well as the percentage change of the Chainlink price since the last update, if the cumulative percentage change in the fast prices over a duration exceeds the cumulative percentage change in the Chainlink prices by a configured threshold, the spread between the fast price and Chainlink price will be automatically enabled. The configuration for this is in Vault.priceFeed.secondaryPriceFeed.maxCumulativeDeltaDiffs.

As the price feed contract may be updated to improve its security, the most reliable way to find the contract address for it would be to check the value of Vault.priceFeed.

BRRR

BRRR is the liquidity provider token of the platform, it can be minted using any of the tokens within the liquidity pool such as ETH, BTC and USDC.

The token’s price is determined by the worth of all tokens within the pool and factoring in the profits and losses of all currently opened positions.

By minting and staking BRRR, users will receive up to 70% of the platform's revenue from fees in the form of Wrapped Ether (WETH), distributed on a weekly basis via the RewardDistributor contract.

Minting and staking can be handled in 1 transaction via the BrrrRewardRouter contract.

Brrr Manager

This contract is fully responsible for controlling the BRRR token supply. It handles minting, burning, adding and removing liquidity from the Vault contract.

It calculates the amount of BRRR to mint/burn based on the assets under management (AUM) of the Vault in USDP.

To add liquidity to the vault for leverage traders to trade against, users call the addLiquidity function, which handles the transfer of tokens to the contract, purchase of USDP debt, and minting of BRRR tokens. Removing liquidity does the same, but in reverse.

OrderBook

The OrderBook contract is crucial for providing users with the ability to place Limit orders, instead of the regular market orders that the PositionRouter contract enables.

Users can open an order for a long/short position, or a swap to open at a specified price, which will be executed by keepers in the event that the price hits their target.

Open orders can be cancelled, or updated at any time by the user, up until the point of execution.

OrderExecutor

This contract is responsible for executing orders on the OrderBook. Once an open orders pre-defined conditions are met, keepers can use this contract to execute these positions, creating an open position on the vault.

Timelock

The governance contract for the majority of smart contracts in the ecosystem.

It contains functions to call the main functions for core smart contracts, most of which are subject to a delay.

In order to execute a function, the admin must first signal intent to execute the function. After the admin has signalled a function, it will be subject to a buffer period, after which, they can call the function that has been signalled.

The signal is stored as a hash of the function name and arguments, packed into a 32 bytes variable. The function call must match the arguments in order to be validated in the _validateAction function, so the admin can't mislead users with incorrect arguments.

This buffer period gives users ample time to exit positions in the event of a malicious action.

Referral Storage

This contract is responsible for all referral functionality. Users can register 32 byte referral codes, which if utilized by another user, will provide the user discounted trading fees, and the owner of the code will earn a rebate.

The deployer is able to create numerous tiers, offering varying rewards. The lowest tier with the lowest reward will typically be the most available, with higher tiers offering higher rewards being reserved for the most active users, or partners of the protocol.

BrrrRewardRouter

BrrrRewardRouter is the peripheral contract of the BrrManager contract. It handles the minting and staking of BRRR tokens in one transaction, so the user instantly begins to benefit from the WETH rewards.

Users are able to unstake and redeem their staked BRRR tokens at any time, for any of the index assets in the Vault.

WETH rewards can be claimed at any time by calling the claim function.

RewardTracker

This contract is used represent staked BRRR tokens. Users can deposit the depositTokens into the contract to earn an equivalent amount of RewardTracker tokens.

The contract controls the calculation and distribution of rewardToken to stakers, by calling the distribute function on the RewardDistributor contract, which users can claim at any time.

The reward rate will be dependent on the tokensPerInterval variable within the RewardDistributor contract, which is set on a weekly basis and determined by the amount of fees accumulated by the platform.

RewardTracker or staked BRRR holders will collectively share up to 70% of the platform's fees.

BrrrXpAmplifier

This novel contract is an extension on top of the RewardTracker contract.

It is designed to allow users to lock their staked BRRR tokens (or RewardTracker tokens) into the contract for different periods of time, in order to earn XP rewards (the amount of XP a user earns will contribute to the total amount of $PRINT tokens they are airdropped at the end of the season).

Users won't earn any XP from their BRRR unless they lock it into the contract. The durations vs rewards are as follows:

• Tier 1 (No Lock-Up, 1 Hour Cooldown) = 1x XP Rewards.

• Tier 2 (30 Day Duration) = 1.25x XP rewards.

• Tier 3 (90 Day Duration) = 1.5x XP rewards.

• Tier 4 (180 Day Duration) = 2x XP rewards.

Users will still be able to claim their WETH rewards from their staked tokens at any time while tokens are locked in the contract.

TransferStakedBrrr

This contract is required for transferring staked BRRR tokens to another address.

Using the regular transfer function on the RewardTracker contract won't provide the new address with token rewards.

The TransferStakedBrrr contract works by unstaking for one account, then staking for the other account in 1 transaction.

RewardDistributor

This contract is responsible for the handling and distribution of rewards to BRRR stakers.

Fees are collected manually by PRINT3R operators every week, converted into WETH, then transferred into the RewardDistributor.

After the WETH amount has been transferred, the admin must call setTokensPerInterval to set the amount of tokens a user will earn per RewardTracker token, per second for the rest of the distribution period.

The distribute function is called by the RewardTracker contract to transfer WETH from the distributor to the reward tracker so users are able to claim it.