This repository contains a binary smart contract system comprised of many libraries, which together make the Valorem Options V1 Core. The Core contracts provide an option settlement engine upon which more complex systems can be built.
The Core is designed to be gas efficient, minimal, and provide a secure settlement system. The Core consists, primarily, of a settlement engine which allows users to write options, exercise options, redeem claims for assets, and settles assignments of exercises to claims written.
- Clone the git repository
- Copy
.env.templateto.envand replace "XYZ" with yourRPC_URL(e.g., https://mainnet.infura.io/v3/apikey or https://eth-mainnet.g.alchemy.com/v2/apikey) - Run
forge test(this will install dependencies, build the project's smart contracts, and run the unit tests on a local fork of mainnet)
The core exposes an interface for users of the protocol, which is documented in the codebase, additional documentation is provided here.
IOptionSettlementEngine is an
ERC-1155 multi-token
interface extended to provide an interface to the Valorem protocol options
settlement system.
The Type enum contains information about the type of a given token in the
settlement engine.
enum Type {
None,
Option,
Claim
}The TokenNotFound() error occurs when a token is not found in the engine.
error TokenNotFound();The FeeSwept event is emitted when accrued protocol fees for a given token are
swept to the feeTo address.
event FeeSwept(
address indexed token,
address indexed feeTo,
uint256 amount
);The NewOptionType event is emitted when a new unique options chain is created.
event NewOptionType(
uint256 indexed optionId,
address indexed exerciseAsset,
address indexed underlyingAsset,
uint96 exerciseAmount,
uint96 underlyingAmount,
uint40 exerciseTimestamp,
uint40 expiryTimestamp
);The OptionsExercised event is emitted on successful exercise of options.
event OptionsExercised(
uint256 indexed optionId,
address indexed exercisee,
uint112 amount
);The OptionsWritten event is emitted when write is called to write new options.
event OptionsWritten(
uint256 indexed optionId,
address indexed writer,
uint256 claimId,
uint112 amount
);The FeeAccrued event is emitted on write or exercise.
event FeeAccrued(
address indexed asset,
address indexed payor,
uint256 amount
);The ClaimRedeem event is emitted when redeem is called on a Claim.
event ClaimRedeemed(
uint256 indexed claimId,
uint256 indexed optionId,
address indexed redeemer,
address exerciseAsset,
address underlyingAsset,
uint96 exerciseAmount,
uint96 underlyingAmount
);The ExerciseAssigned event is emitted when an exercise of an option is assigned to a claim.
event ExerciseAssigned(
uint256 indexed claimId,
uint256 indexed optionId,
uint112 amountAssigned
);The feeBalance function returns the balance of protocol fees for a given token
which have not been swept yet.
function feeBalance(address token) external view returns (uint256);Returns the protocol fee in basis points charged to writers in the underlying asset and exercisers in the exercise asset.
function feeBps() external view returns (uint8);The feeTo function returns the address to which protocol fees are swept.
function feeTo() external view returns (address);Returns the token Type enum for a given tokenId.
function tokenType(uint256 tokenId) external view returns (Type);Returns Option struct details about a given tokenId if that token is a vToken.
function option(uint256 tokenId)
external
view
returns (Option memory optionInfo);Returns Claim struct details about a given tokenId if that token is a claim NFT.
function claim(uint256 tokenId)
external
view
returns (Claim memory claimInfo);Callable only by the present feeTo address, changes the feeTo address.
function setFeeTo(address newFeeTo) external;Returns the optionId for the hash keccak256(abi.encode(Option memory)) where settlementSeed is set to
0 at the time of hashing if it exists.
function hashToOptionToken(bytes32 hash)
external
view
returns (uint256 optionId);Sweeps the fees if the balance for a token is greater than 1 wei, for each token in
tokens.
function sweepFees(address[] memory tokens) external;Creates a new options chain if one doesn't already exist for the hash keccak256(abi.encode(Option memory)) where settlementSeed is set to
0.
function newOptionType(Option memory optionInfo)
external
returns (uint256 optionId);Writes amount of optionId Option and sends the caller vTokens and a claim NFT.
function write(uint256 optionId, uint112 amount)
external
returns (uint256 claimId);Exercises amount of optionId, transferring in the exercise asset, and
transferring out the underlying asset if all requirements are met.
function exercise(uint256 optionId, uint112 amount) external;Redeems claimId for the underlying asset(s) if msg.sender is the caller and
the options chain for the claim has reached expiry. Burns the claim NFT on success.
function redeem(uint256 claimId) external;Returns the Underlying struct about assets for 1 wei of a given tokenId if
that token exists.
function underlying(uint256 tokenId)
external
view
returns (Underlying memory underlyingPositions);The Claim struct contains information about a claim, generated when a writer calls
write. Every claim is linked to an option token.
struct Claim {
uint256 option;
uint112 amountWritten;
uint112 amountExercised;
bool claimed;
}The Option struct contains all data about an option chain/token and is keyed on the
unique hash keccak256(abi.encode(Option memory)) where settlementSeed is set to
0 at the time of hashing.
struct Option {
address underlyingAsset;
uint40 exerciseTimestamp;
uint40 expiryTimestamp;
address exerciseAsset;
uint96 underlyingAmount;
uint160 settlementSeed;
uint96 exerciseAmount;
}The Underlying struct contains information about the underlying assets for 1
wei of a given token ID in the settlement engine.
struct Underlying {
address underlyingAsset;
int256 underlyingPosition;
address exerciseAsset;
int256 exercisePosition;
}