@perennial/v2-periphery
Advanced tools
Extension systems and periphery contracts for the Perennial V2 Protocol
Collateral accounts help users manage collateral across Perennial markets on a single chain. A user's EOA may deploy only one collateral account, whose address is deterministic. Actions are performed using EIP-712 message payloads submitted to keepers through a relayer. Users may self-sign their messages or delegate one or more signers.
Users may also relay requests through this extention to compensate keepers from their collateral account.
A single Controller is deployed to a chain. The controller serves as a factory to deploy Account contracts, and manages interactions between accounts and multiple Market contracts. Collateral accounts are only compatible with markets which use DSU as collateral.
Account offers facilities to deposit and withdraw tokens, and to transfer collateral into and out of markets. Controller employs these facilities to perform actions requested by the account owner or a delegated signer, such as rebalancing collateral across markets.
Users send signed messages to a Relayer which queues them in a centralized database. Keepers dequeue messages from the relayer, and submit them to the controller to be compensated. Keepers also interact with the controller to find opportunities to rebalance accounts, and are compensated for performing successful rebalances.
Most operations may be performed in a gasless manner using signed messages.
Account.deposit functionAll USDC in the account is implicitly wrapped to DSU when transferring an amount greater than the account's DSU balance into a market. Funds transferred out of markets are not unwrapped until withdrawal. These behaviors minimize gas cost when rebalancing.
When withdrawing funds from the account, a flag allows the caller to explicitly control unwrapping behavior.
After the account owner has configured a rebalance group, keepers may call Controller.checkGroup offchain to determine if the group may be rebalanced. Assuming state does not change beforehand, the keeper may then call Controller.rebalanceGroup to perform a rebalance.
To build a list of rebalance groups to check, keepers may watch for RebalanceGroupConfigured events emitted by the Controller. An event with an empty markets collection indicates the group was deleted.
With respect to domains, messages fall into three categories. Here's how to set your domain for each:
| Message type | Message domain |
|---|---|
| Messages involving Collateral Account actions | Collateral Accounts Controller |
| Nonce cancellation requests | Validator used for intents |
| Market access requests | Market Factory |
Nonces are hashed into each request to ensure the same signed action cannot be replayed. Two types of nonces are specified in every message:
The group nonce may be used to atomically cancel multiple actions. Let's explore a few use cases:
Messages may be relayed to MarketFactory and other extensions for purposes of compensating keepers using funds in your collateral account. "Inner" relayed messages are wrapped with an "Outer" message which identifies your collateral account and a maximum fee to compensate the keeper. Both inner and outer message require separate signatures against different domains (discussed above).
// TODO: document interactions with relayer and controller
Generally a subclass such as Controller_Arbitrum will be deployed to the target chain. The base Controller has no facilities for keeper compensation or message relaying but is not abstract. It may be deployed for testing purposes or to self-process signed messages.
Trigger Orders allow users to submit an order to increase or decrease a position when the market price moves above or below a user-chosen limit price. This is accomplished by storing the trigger order onchain, and allowing keepers to execute trigger orders whose entry conditions have been met.
A single Manager is created for each Perennial deployment, accompianied by an OrderVerifier contract to handle signed messages. Users add the Manager as an operator for their account. Trigger Orders are only compatible with markets which use DSU as collateral.
For executing orders and handling signed messages, keepers are compensated from the market in which the order was placed.
All operations may be performed in a gasless manner using signed messages. Users must create and fund a Collateral Account, which will be used to compensate keepers for processing signed messages and for executing orders. Users must also approve the trigger order Manager contract as an operator for themselves (not for their collateral account).
contracts/types/TriggerOrder documentation for details.placeOrder directly on the Manager, or sign and send a PlaceOrderAction message to a relayer.placeOrder or send a PlaceOrderAction using the same order nonce as the unexecuted order you wish to replace. This will overwrite the unexecuted order in storage.PlaceOrderAction message was handled, call cancelOrder directly on the Manager, or sign and send a CancelOrderAction message to a relayer.OrderVerifier contract.Message domain should be set to the Manager contract address.
Note the message nonce works independently from the order nonce. If you choose to set message nonce equal to order nonce, you'll need a different scheme to assign nonces to cancellation and replacement messages. For example, you could use a serial order/message nonce, incrementing from 0. But for non-placement messages, you could decrement the serial nonce from type(uint256).max.
Nonces are hashed into each request to ensure the same signed action cannot be replayed. Two types of nonces are specified in every message:
The group nonce may be used to atomically cancel multiple actions. Let's explore a few use cases:
Keepers should:
checkOrder facility which may be called offchain prior to executing. Alternatively, keeper can use a transaction simulation API to confirm the execution will be successful and ensure they will be paid appropriately for transacting.Manager_Arbitrum and Verifier will be deployed to the target chain.
( to be documented )
( to be documented )
Before running any command, make sure to install dependencies. Run this in the root workspace as well to capture package patches:
$ yarn
Compile the smart contracts with Hardhat:
$ yarn compile
This also generates the Typechain types
Run the Mocha tests:
$ yarn test
$ yarn test:integration
$ yarn test:integrationArbitrum
$ yarn test:integrationBase
Ensure JSON-RPC node URLs have been defined in your root .env file.
To get a gas report based on unit test calls:
$ yarn gasReport
npx hardhat run --network rinkeby ./scripts/deploy.ts
npx hardhat verify --network <network> <DEPLOYED_CONTRACT_ADDRESS> "Constructor argument 1"
FAQs
Perennial V2 Periphery
We found that @perennial/v2-periphery demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Experts push back on new claims about AI-driven ransomware, warning that hype and sponsored research are distorting how the threat is understood.
Security News
Ruby's creator Matz assumes control of RubyGems and Bundler repositories while former maintainers agree to step back and transfer all rights to end the dispute.
Research
/Security News
Socket researchers found 10 typosquatted npm packages that auto-run on install, show fake CAPTCHAs, fingerprint by IP, and deploy a credential stealer.