Developer Overview

Overview

Royco allows anyone to create a market around any onchain action (an IAM). Those who wish to pay users to execute an onchain action are called "Incentive Providers" (IPs) and offer token or points incentives in exchange for an "Action Provider" (APs) to take some action. Actions are one of two types: depositing in a staking vault, or executing some “recipe” of one or more smart contract interactions. The former type forms Royco’s “Vault Markets” while the latter type forms Royco’s “Recipe Markets”. Royco users can fund orders on both market types using their current positions in ERC4626i vaults, as long as the deposit tokens match. Finally, users can place onchain intents that enable negotiation.

This documentation covers all the smart contracts involved in the Royco protocol, targeting developers who wish to interact with or build upon the protocol.

Components

Vault Markets

Actions which deposit in staking vaults are called "Vault Markets". Vault Markets consist of a Royco ERC4626i Vault, which wraps an underlying ERC4626 vault to distribute incentives to depositors, and a Royco Vault Orderbook which allows APs to place limit orders on these vaults to express what incentive rates they would need to receive in order to deposit.

ERC4626i

Vault Markets center around ERC4626i vaults, the 'i' standing for "incentives". 4626i vaults are created by the ERC4626iFactory by simply pointing to an existing 4626 vault and deploying a new ERC4626i wrapper. IPs can then distribute Unipool style staking incentives to APs who deposit in the vault through the wrapper. The underlying 4626 vault must be fully compliant to vanilla 4626 behavior, meaning working previewWithdraw functions, immediate deposits/withdrawals, etc.

ERC4626i vaults are owned by the Incentive Provider who deploys them. The IP who owns a 4626i vault is solely permissioned to distribute incentives, and may add additional incentive tokens or points campaigns at any time, (for up to 20 different assets). IPs can also "extend" incentive campaigns by calling extendRewardsInterval, however to prevent dishonest AP limit order sniping, IPs must keep the new rewards rate equivalent or higher than the current rewards rate when doing so.

VaultOrderbook

The Vault Orderbook is where APs offer to deposit into 4626i vaults. APs place "limit orders" on vaults specifying the token rates they would need to receive per deposit token in order to be allocated into a vault. Once a vault is streaming the rate desired by the LP, an IP can call allocateOrder to draw the in-range orders into the pool. After allocation, rates will continue to fluctuate as incentives are added or people enter/exit the vault.

Orders on Royco Orderbooks are placed without transferring tokens to the orderbook, allowing many orders to be placed off of the same tokens. Additionally, orders can be placed against not only ERC20 tokens but also against other 4626 or 4626i vaults, withdrawing from the vaults on order fill to allow APs to farm one pool while simultaneously offering to enter other pools if incentive rates increase.

Recipe Markets

More long-tail actions which may not be easily represented by 4626 vaults instead occur through recipe markets, which heavily rely on the operation-chaining/scripting language Weiroll. Weiroll allows IPs to write complex chained "Recipes" of smart contract interactions that can express any chain of actions you could make through an EOA.

WeirollWallet

Instead of depositing in a 4626i vault, recipe markets deposit assets into a lightweight, disposable, smart contract wallet owned by the AP with the Weiroll VM built in. This allows the AP to execute weiroll scripts without exposing all their funds to the arbitrary (and potentially malicious) interactions given by the script. Weiroll Wallets also allow locking the wallet itself, enabling IPs to ensure an AP holds their position after executing the script for some set amount of time.

After a timelock has expired, an AP gains full control over the wallet, and is now able to call a withdrawal recipe specified in the market, or can simply pass raw calldata for the wallet to execute.

Recipe Orderbook

Recipe Orderbook functions much like Vault Orderbook, but allows Incentive Providers to also place limit orders, stating that they are willing to pay APs some amount of incentive in exchange for calling the Weiroll recipe with some amount of deposit token. Both LP and AP limit orders may be filled by the opposite parties.