Skip to main content

Transmuter

Description​

The Transmuter is a contract that allows redemption of synthetic debt assets created by associated AlchemistV3 contracts for the underlying assets that back them at a 1 to 1 ratio. Deposits of synthetic debt assets into the Transmuter create demand for underlying assets from AlchemistV3 instances, which are obligated to service that demand across a pre-set time period. This creates fixed-duration fixed-rate terms. Each Transmuter takes one synthetic debt asset (alAsset) and can be associated with multiple AlchemistV3 instances, however only one AlchemistV3 instance is used for redemptions.

Variables​

StakingPosition​

A struct that describes a tranche of deposited synthetic debt assets which have an eventual claim to underlying.

amount
startBlock
maturationBlock

TransmuterInititializationParams​

State set by params at creation-time of the transmuter to initially configure it.

syntheticToken
timeToTransmute
transmutationFee
exitFee
protocolFeeReceiver
admin
graphSize
  • Description - the size in blocks of the transmuter staking graph. Used to optimize the amount of reads and writes made to the graph and can be extended over time.
  • Type - address
  • Used By
    • TODO - doesn't seem to be used anywhere
  • Updated By
    • TODO - doesn't seem to be used anywhere
  • Read By
    • graphSize()
  • Nofified By

Constants​

Immutable variables used as helpers or for informational purposes.

BPS
FIXED_POINT_SCALAR
  • Description - A multiplier that is used to be able to do fixed point math, since solidity does not natively handle decimals. Like ERC20 tokens which typically use 18 decimals, it expresses 1 as 1e18. Anything less is a fraction of 1.
  • Type - uint256
  • Used By
  • Updated By
    • NONE - immutable variable
BLOCK_SCALING_FACTOR
  • Description - A constant set to 1e18. Used as a fixed-point scaling factor when dividing token amounts by block counts, allowing precise ratios to be stored in the staking graph.
  • Type - uint256
  • Used By
  • Updated By
    • NONE - immutable variable
version
  • Description - Constant expressing Alchemix version. Not used for anything in the contract.
  • Type - uint256
  • Updated By
    • NONE - immutable variable
  • Read By
    • version()

Public State​

State that is available and can be read from outside of the contract.

Uint256​

depositCap
totalLocked

Addresses​

pendingAdmin
alchemist
alchemists
  • Description - An array of alchemists associated with this Transmuter.
  • Type - address[]
  • Used By
    • TODO - not used anywhere?
  • Updated By
    • TODO - not updated anywhere
  • Read By
    • alchemists()

Private State​

Internal state of the contract. In most cases cannot be read from outside of the contract. In some cases certain aspects can be read using specific functions. (See ReadingState)

_positions
_stakingGraph
_nonce

Functions​

User Actions​

Functions that can be called by external accounts which influence the state or balance of the Transmuter.

createRedemption(uint256 syntheticDepositAmount)
  • Description - Creates a time-locked redemption staked position that linearly vests over timeToTransmute blocks.

    Validates the deposit amount and capacity against both depositCap and alchemist.totalSyntheticsIssued(). Transfers the syntheticDepositAmount of alAsset from the function caller. Records a new StakingPosition to Transmuter from block.number to block.number + timeToTransmute. Updates the staking graph with the per-block redemption rate contributed by this position, adding it to the existing global rate so that redemptions for all positions can be served correctly. Mints a new position token and updates totalLocked.

    • @param syntheticDepositAmount - amount of syntheticToken deposited in this staking position, to be locked until transmutation is finished or early exit is executed.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
    • PositionCreated(address owner, uint256 amount, uint256 tokenId)
  • Reverts
    • DepositZeroAmount() - if syntheticDepositAmount == 0
    • DepositCapReached() - if totalLocked + syntheticDepositAmount exceeds depositCap or alchemist.totalSyntheticsIssued(). In the latter case there must be enough debt in the system to be able to service redemptions, and this check ensures that more deposits are not accepted than there is debt for service them.
claimRedemption(uint256 id)
  • Description - Settles and closes the redemption for the staked position identified by id, paying out the vested portion in yield tokens and returning any unvested synthetics minus fees applied.

    Validates the position exists and is not being claimed in its creation block. Computes the vested vs. unvested split using block-based linear vesting. Verifies ownership and burns the position token. Calculates bad debt from Alchemist state and scales down vested payout if necessary. First uses yield from prior repayments to reduce redemptions, then redeems the rest from the Alchemist. (calls alchemist.redeem()) Applies the transmutation fee to "transmuted" or vested debt, and an exit fee to synthetics returned (unvested debt). If the staked position was not fully transmuted (vested) then the staking graph is updated to to remove the remaining per block rate. Transfers yield and synthetic payouts/fees, burns the transmuted synthetics, reduces totalSyntheticsIssued, (calls alchemist.reduceSyntheticsIssued()) decrements totalLocked, and deletes the position. Informs the alchemist of it's yieldToken quantity. (calls alchemist.setTrasnmuterTokenBalance())

    • @param id - the id of the staked position to claim and close
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
    • PositionClaimed(address owner, uint256 claimDebt, uint256 syntheticReturned)
  • Reverts
    • PositionNotFound() - if no position for id
    • PrematureClaim() - if claiming in the same block the position was opened
    • CallerNotOwner() - if the message sender does not own the position
acceptAdmin()

Admin Actions​

Functions guarded by the onlyAdmin modifier.

setPendingAdmin(address value)
  • Description - Sets the pending admin. First part of a two-step process to change the admin. The second step is the pendingAdmin accepting the role by calling acceptAdmin.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - none
setAlchemist(address value)
  • Description - Sets the address of the AlchemistV3 contract that will be used to redeem against for this Transmuter.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - none
setDepositCap(uint256 cap)
  • Description - Sets the deposit cap variable, or maximum amount of synthetics that can be staked in the transmuter at any one time.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - If the cap is greater than or equal to the max value of uint256.
setTransmutationFee(uint256 fee)
  • Description - Sets the fee as a percentage in BPS for transmutation.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - If the fee is greater than or equal to the max of BPS (>= 100%)
setExitFee(uint256 fee)
  • Description - Sets the fee as a percentage in BPS for early exits from positions staked for transmutation.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - If the fee is greater than or equal to the max of BPS (>= 100%)
setTransmutationTime(uint256 time)
  • Description - Sets the duration of time it takes for new staked positions of synthetic assets to be transmuted in blocks.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - none
setProtocolFeeReceiver(address value)
  • Description - Sets the address that wil recieve fees from the Transmuter.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits
  • Reverts - none

Internal Operations​

Functions that are cannot be called by other contracts or EOAs. Used only as helpers for performing internal logic.

_updateStakingGraph(int256 amount, uint256 blocks)
  • Description - Updates the staking graph with a new redemption schedule starting at the current block.

    Delegates to _stakingGraph.addStake(amount, block.number, blocks). Positive amount values add per-block redemption weight, negative values remove it. The change applies for the amount of passed in blocks.

    • @param amount - scaled redemption amount to apply (scaled by BLOCK_SCALING_FACTOR)
    • @param blocks - number of blocks over which the amount should apply
  • Visibility Specifier - private
  • State Mutability Specifier - nonpayable
  • Returns - none
  • Emits - none
  • Reverts - none
_checkArgument(bool expression)
  • Description - Validates a boolean condition intended to check arguments.
    • @param expression - the boolean expression to validate
  • Visibility Specifier - internal
  • State Mutability Specifier - pure
  • Returns - none
  • Emits - none
  • Reverts
    • IllegalArgument() - if the expression evaluates to false
_checkState(bool expression)
  • Description - Validates a boolean condition intended to check state.
    • @param expression - the boolean expression to validate
  • Visibility Specifier - internal
  • State Mutability Specifier - pure
  • Returns - none
  • Emits - none
  • Reverts - IllegalState() if the expression evaluates to false

Reading State​

Reads derived, calculated, or internal state. For getters of public variables see the Variable section.

tokenUri(uint256 id)
  • Description - Gets the token URI for a Transmuter NFT token with a specfic id.
  • Visibility Specifier - public
  • State Mutability Specifier - view
  • Returns - string memory - the URI of the Transmuter NFT with the passed ID
  • Emits - none
  • Reverts - none
getPosition(uint256 id)
  • Description - Gets the StakingPosition identified by id.
  • Visibility Specifier - external
  • State Mutability Specifier - view
  • Returns - StakingPosition memory
  • Emits - none
  • Reverts - none
queryGraph(uint256 startBlock, uint256 endBlock)
  • Description - Allows callers to see how much is scheduled to be redeemed between two blocks numbers.

    Queries the staking graph to calculate the total redemption amount that is scheduled to be applied for all staked positions between two block numbers by delegating to _stakingGraph.queryStake(startBlock, endBlock). If the query does not find an amount for that block span then it returns 0. Otherwise, it divides the queried amount to be redeemed (stored as a scaled uint256) by BLOCK_SCALING_FACTOR to restore to token units and returns the result.

    • @param startBlock - block number at which to start the query range
    • @param endBlock - block number at which to end the query range
  • Visibility Specifier - external
  • State Mutability Specifier - view
  • Returns - uint256 scheduledAmountToBeRedeemed - total expected redemption amount of scheduled redemptions between the start and end blocks in token units.
  • Emits - none
  • Reverts - none

Events​

  • AdminUpdated(address admin) - Emitted when the admin address is updated.
  • PendingAdminUpdated(address pendingAdmin) - Emitted when the pending admin is updated.
  • AlchemistUpdated(address alchemist) - Emitted when the associated alchemist is updated.
  • PositionCreated(address indexed creator, uint256 amountStaked, uint256 nftId) - Emitted when a position is created.
  • PositionClaimed(address indexed claimer, uint256 amountClaimed, uint256 amountUnclaimed) - Emitted when a position is claimed.
  • GraphSizeUpdated(uint256 size) - Emitted when the graph size is extended.
  • DepositCapUpdated(uint256 cap) - Emitted when the deposit cap is updated.
  • TransmutationTimeUpdated(uint256 time) - Emitted when the transmutation time is updated.
  • TransmutationFeeUpdated(uint256 fee) - Emitted when the transmutation fee is updated.
  • ExitFeeUpdated(uint256 fee) - Emitted when the early exit fee is updated.
  • ProtocolFeeReceiverUpdated(address receiver) - Emitted when the fee receiver is updated.