IDerivative
Interface for Derivative functionality
Derivatives provide a mechanism to create synthetic assets that are backed by collateral, such as base tokens from an auction.
Functions
tokenMetadata
The metadata for a derivative token
function tokenMetadata(
uint256 tokenId
)
external
view
returns (
bool exists,
address wrapped,
address underlyingToken,
uint256 supply,
bytes memory data
);
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The ID of the derivative token |
Returns
| Name | Type | Description |
|---|---|---|
exists | bool | True if the token has been deployed |
wrapped | address | Non-zero if an ERC20-wrapped derivative has been deployed |
underlyingToken | address | The address of the underlying token |
supply | uint256 | The total supply of the derivative token |
data | bytes | Implementation-specific data |
deploy
Deploy a new derivative token. Optionally, deploys an ERC20 wrapper for composability.
function deploy(
address underlyingToken_,
bytes memory params_,
bool wrapped_
) external returns (uint256 tokenId_, address wrappedAddress_);
Parameters
| Name | Type | Description |
|---|---|---|
underlyingToken_ | address | The address of the underlying token |
params_ | bytes | ABI-encoded parameters for the derivative to be created |
wrapped_ | bool | Whether (true) or not (false) the derivative should be wrapped in an ERC20 token for composability |
Returns
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the newly created derivative token |
wrappedAddress_ | address | The address of the ERC20 wrapped derivative token, if wrapped_ is true, otherwise, it's the zero address. |
mint
Mint new derivative tokens.
Deploys the derivative token if it does not already exist.
The module is expected to transfer the collateral token to itself.
function mint(
address to_,
address underlyingToken_,
bytes memory params_,
uint256 amount_,
bool wrapped_
) external returns (uint256 tokenId_, address wrappedAddress_, uint256 amountCreated_);
Parameters
| Name | Type | Description |
|---|---|---|
to_ | address | The address to mint the derivative tokens to |
underlyingToken_ | address | The address of the underlying token |
params_ | bytes | ABI-encoded parameters for the derivative to be created |
amount_ | uint256 | The amount of derivative tokens to create |
wrapped_ | bool | Whether (true) or not (false) the derivative should be wrapped in an ERC20 token for composability |
Returns
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the newly created derivative token |
wrappedAddress_ | address | The address of the ERC20 wrapped derivative token, if wrapped_ is true, otherwise, it's the zero address. |
amountCreated_ | uint256 | The amount of derivative tokens created |
mint
Mint new derivative tokens for a specific token ID
function mint(
address to_,
uint256 tokenId_,
uint256 amount_,
bool wrapped_
) external returns (uint256, address, uint256);
Parameters
| Name | Type | Description |
|---|---|---|
to_ | address | The address to mint the derivative tokens to |
tokenId_ | uint256 | The ID of the derivative token |
amount_ | uint256 | The amount of derivative tokens to create |
wrapped_ | bool | Whether (true) or not (false) the derivative should be wrapped in an ERC20 token for composability |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | tokenId_ The ID of the derivative token |
<none> | address | wrappedAddress* The address of the ERC20 wrapped derivative token, if wrapped* is true, otherwise, it's the zero address. |
<none> | uint256 | amountCreated_ The amount of derivative tokens created |
redeemMax
Redeem all available derivative tokens for underlying collateral
function redeemMax(uint256 tokenId_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to redeem |
redeem
Redeem derivative tokens for underlying collateral
function redeem(uint256 tokenId_, uint256 amount_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to redeem |
amount_ | uint256 | The amount of derivative tokens to redeem |
redeemable
Determines the amount of redeemable tokens for a given derivative token
function redeemable(address owner_, uint256 tokenId_) external view returns (uint256 amount);
Parameters
| Name | Type | Description |
|---|---|---|
owner_ | address | The owner of the derivative token |
tokenId_ | uint256 | The ID of the derivative token |
Returns
| Name | Type | Description |
|---|---|---|
amount | uint256 | The amount of redeemable tokens |
exercise
Exercise a conversion of the derivative token per the specific implementation logic
Used for options or other derivatives with convertible options, e.g. Rage vesting.
function exercise(uint256 tokenId_, uint256 amount) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to exercise |
amount | uint256 | The amount of derivative tokens to exercise |
exerciseCost
Determines the cost to exercise a derivative token in the quoted token
Used for options or other derivatives with convertible options, e.g. Rage vesting.
function exerciseCost(uint256 tokenId_, uint256 amount) external view returns (uint256 cost);
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to exercise |
amount | uint256 | The amount of derivative tokens to exercise |
Returns
| Name | Type | Description |
|---|---|---|
cost | uint256 | The cost to exercise the derivative token |
reclaim
Reclaim posted collateral for a derivative token which can no longer be exercised
Access controlled: only callable by the derivative issuer via the auction house.
function reclaim(uint256 tokenId_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to reclaim |
transform
Transforms an existing derivative issued by this contract into something else. Derivative is burned and collateral sent to the auction house.
Access controlled: only callable by the auction house.
function transform(uint256 tokenId_, address from_, uint256 amount_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to transform |
from_ | address | The address of the owner of the derivative token |
amount_ | uint256 | The amount of derivative tokens to transform |
wrap
Wrap an existing derivative into an ERC20 token for composability Deploys the ERC20 wrapper if it does not already exist
function wrap(uint256 tokenId_, uint256 amount_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to wrap |
amount_ | uint256 | The amount of derivative tokens to wrap |
unwrap
Unwrap an ERC20 derivative token into the underlying ERC6909 derivative
function unwrap(uint256 tokenId_, uint256 amount_) external;
Parameters
| Name | Type | Description |
|---|---|---|
tokenId_ | uint256 | The ID of the derivative token to unwrap |
amount_ | uint256 | The amount of derivative tokens to unwrap |
validate
Validate derivative params for the specific implementation
The parameters should be the same as what is passed into deploy() or mint()
function validate(
address underlyingToken_,
bytes memory params_
) external view returns (bool isValid);
Parameters
| Name | Type | Description |
|---|---|---|
underlyingToken_ | address | The address of the underlying token |
params_ | bytes | The params to validate |
Returns
| Name | Type | Description |
|---|---|---|
isValid | bool | Whether or not the params are valid |
computeId
Compute a unique token ID, given the parameters for the derivative
function computeId(
address underlyingToken_,
bytes memory params_
) external pure returns (uint256 tokenId);
Parameters
| Name | Type | Description |
|---|---|---|
underlyingToken_ | address | The address of the underlying token |
params_ | bytes | The parameters for the derivative |
Returns
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The unique token ID |
getTokenMetadata
Get the metadata for a derivative token
function getTokenMetadata(uint256 tokenId) external view returns (Token memory tokenData);
Parameters
| Name | Type | Description |
|---|---|---|
tokenId | uint256 | The ID of the derivative token |
Returns
| Name | Type | Description |
|---|---|---|
tokenData | Token | The metadata for the derivative token |
Errors
Derivative_NotImplemented
error Derivative_NotImplemented();
Structs
Token
Metadata for a derivative token
struct Token {
bool exists;
address wrapped;
address underlyingToken;
uint256 supply;
bytes data;
}
Properties
| Name | Type | Description |
|---|---|---|
exists | bool | True if the token has been deployed |
wrapped | address | Non-zero if an ERC20-wrapped derivative has been deployed |
underlyingToken | address | The address of the underlying token |
supply | uint256 | The total supply of the derivative token |
data | bytes | Implementation-specific data |