Fractional v2 contest

Fractional v2 contest details

• $71,250 USDC main award pot
• $3,750 USDC gas optimization award pot
• Join C4 Discord to register
• Submit findings using the C4 form
• Read our guidelines for more details
• Starts July 7, 2022 20:00 UTC
• Ends July 14, 2022 20:00 UTC

Contest Scope

This contest is open for one week to give wardens time to understand the protocol properly. Representatives from Fractional will be available in the Code Arena Discord to answer any questions during the contest period. The focus of the contest is to try and find any logic errors, mint/burn fractions unexpectedly, or ways to remove NFTs from the Fractional Vaults in ways that would be beneficial for an attacker at the expense of vault creators or fraction holders. Wardens should assume that governance variables are set sensibly (unless they can find a way to change the value of a governance variable, and not counting social engineering approaches for this).

Protocol Overview

The Fractional v2 Protocol is designed around the concept of Hyperstructures

Hyperstructures: Crypto protocols that can run for free and forever, without maintenance, interruption, or intermediaries

Fractional is a decentralized protocol that allows for shared ownership and governance of NFTs. When an NFT is fractionalized, the newly minted tokens function as normal ERC-1155 tokens which govern the non-custodial Vault containing the NFT(s).

Vaults

The home of all items on Fractional

Vaults are a slightly modified implementation of PRBProxy which is a basic and non-upgradeable proxy contract. Think of a Vault as a smart wallet that enables the execution of arbitrary smart contract calls in a single transaction. Generally, the calls a Vault can make are disabled and must be explicitly allowed through permissions. The vault is intentionally left unopinionated and extremely flexible for experimentation in the future.

Permissions

Authorize transactions performed on a vault

A permission is a combination of a Module contract, Target contract, and specific function Selector in a target contract that can be executed by the vault. A group of permissions creates the set of functions that are callable on the Vault in order to carry out its specific use case. Each permission is then hashed and used as a leaf node to generate a merkle tree, where the merkle root of the tree is stored on the vault itself. Whenever a transaction is executed on a vault, a merkle proof is used to verify legitimacy of the leaf node (Permission) and the Merkle root.

For example, a vault involved in an active buyout will need permission to burn fractional tokens. Therefore, a permission will be set on the deployment of the vault that consists of the Buyout contract address (Module), Supply contract address (Target), and a burn function (Selector) which is declared in the Supply contract. This same process will then be repeated for all pre-defined actions that a vault may want, such as minting fractional tokens or transferring assets out of the vault.

Modules

Make vaults do cool stuff

Modules are the bread and butter of what makes Fractional unique. At Vault creation, modules are added to permissions for the vault. Each module should have specific goals it plans to accomplish. Some general examples are Buyouts, Inflation, Migration, and Renting. If a vault wants to update the set of modules enabled, then it must have the migration module enabled and go through the migration process.

In general, it is highly recommended for vaults to have a module that enables items to be removed from vaults. Without this, all items inside of a vault will be stuck forever.

Protoforms

Protoforms are templates for common vault use-cases

Protoforms aggregate static sets of module permissions to deploy vaults with similar base functionality. Protoforms are the main entry point for deploying a vault with a certain use-case determined by the modules that are enabled on a vault.

Targets

Execute vault transactions

Targets are stateless script-like contracts for executing transactions by the Vault on-behalf of a user. Only functions of a target contract that are initially set as enabled permissions for a vault can be executed by a vault.

Smart Contracts

All the contracts in this section are to be reviewed. Any contracts not in this list are to be ignored for this contest.

BaseVault.sol

External Contracts: IERC20, IERC721, IERC1155, IModule, IVaultRegistry

Buyout.sol

External Contracts: IERC1155, ISupply, ITransfer, IVault, IVaultRegistry

IBaseVault.sol

External Contracts: IProtoform

IBuyout.sol

External Contracts: IModule

IMinter.sol

External Contracts: IModule

FERC1155.sol

External Contracts: IFERC1155, INFTReceiver

Libraries: clones-with-immutable-args/src/Clone.sol, @rari-capital/solmate/src/tokens/ERC1155.sol

Migration.sol

External Contracts: IBuyout, IERC20, IERC721, IERC1155, IFERC1155, IModule, IVaultRegistry

Libraries: @rari-capital/solmate/src/utils/ReentrancyGuard.sol

Minter.sol

External Contracts: IVault

SafeSend.sol

Libraries: @rari-capital/solmate/src/tokens/WETH.sol

Supply.sol

External Contracts: IVaultRegistry

Transfer.sol

External Contracts: IERC20, IERC721, IERC1155

Vault.sol

Libraries: @openzeppelin/contracts/utils/cryptography/MerkleProof.sol

VaultFactory.sol

External Contracts: Vault

Libraries: clones-with-immutable-args/src/Create2ClonesWithImmutableArgs.sol

VaultRegistry.sol

External Contracts: FERC1155, IVault, VaultFactory

Libraries: clones-with-immutable-args/src/ClonesWithImmutableArgs.sol

Areas of concern for Wardens

We would like wardens to focus on any core functional logic, boundary case errors, or similar issues which could be utilized by an attacker to take assets away from fraction holders or vault curators who deposit assets into the Vaults. Any errors may be submitted by wardens for review and potential reward as per the normal issue impact prioritization. Gas optimizations are welcome but not the main focus of this contest and thus at most 5% of the contest reward will be allocated to gas optimizations. For gas optimizations, the most important flows are BaseVault deployment, buyout claims/withdrawals, and migration flows.

If wardens are unclear on which areas to look at or which areas are important please feel free to ask in the contest Discord channel.

Tests

A full set of unit tests are provided in the repo. To run these do the following:

Prepare Environment

1. install node, refer to nodejs

2. install foundry, refer to foundry

Setup Environment

Required node >12

1. run make deps in root directory - Installs gitmodule dependencies

2. create .env file in root directory and add the following:

ALCHEMY_API_KEY=0000000000000000000000000000000000000000000000000000000000000000
DEPLOYER_PRIVATE_KEY=0000000000000000000000000000000000000000000000000000000000000000
ETHERSCAN_API_KEY=0000000000000000000000000000000000000000000000000000000000000000

3. run npm ci in root directory - Installs node dependencies

4. run make users - Generates user proxies

5. run make test - Runs foundry tests

Slither

Slither will fail when you try to run it locally due to issues with top-level constants inside Yul blocks as well as custom reverts being used from interface contracts that are not inherited. If you would still like to run it, the following commands will need to be run to fix those issues:

curl https://gist.githubusercontent.com/mehtaculous/5794ad3a8bcde2c0a52015d546acc741/raw/47210d6c67d273bbb70e558958054d678d43db5b/Supply.sol > src/targets/Supply.sol

curl https://gist.githubusercontent.com/mehtaculous/642887f238dd55dda6a20cdf9b5a5474/raw/22212bd1848d1316085371d33647f650d307c591/Transfer.sol > src/targets/Transfer.sol

curl https://gist.githubusercontent.com/mehtaculous/b17776dc0d0c5c93948c10361d37cfe1/raw/892f9ac1894f12c40cf731e047a0a328f2c4d0fa/Metadata.sol > src/utils/Metadata.sol

curl https://gist.githubusercontent.com/mehtaculous/9c094ce7d652dd7d552a6dc5501c7fef/raw/a418270fe54f61b328fa0be8a27d0dadb09a2567/Migration.sol > src/modules/Migration.sol

Glossary