Skip to main content

The AlchemistV3Position contract is an ERC721 NFT that represents individual user positions in the Alchemist. Each position has a unique token ID that maps to an Account in the AlchemistV3 contract, tracking the user's deposited collateral and outstanding debt. Only the associated AlchemistV3 contract can mint and burn position tokens. When a position NFT is transferred, all mint allowances (approveMint) on that position are automatically reset.

Variables​

alchemist
admin
  • Description - The address authorized to update the metadata renderer and transfer admin rights. Set on deployment.
  • Type - address
  • Used By
  • Updated By
  • Read By - admin()
metadataRenderer

Modifiers​

onlyAlchemist
  • Description - Restricts function execution to the alchemist address.
  • Reverts
    • CallerNotAlchemist() - when msg.sender is not the Alchemist contract.
onlyAdmin
  • Description - Restricts function execution to the admin address.
  • Reverts
    • CallerNotAdmin() - when msg.sender is not the admin.

Functions​

Alchemist Actions​

Functions that can only be called by the AlchemistV3 contract.

mint(address to)
  • Description - Mints a new position NFT to the specified address. Increments the internal token ID counter and assigns the new ID to the recipient.
    • @param to - The address to receive the newly minted position NFT.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Returns - uint256 - the unique token ID of the newly minted position.
  • Reverts
    • CallerNotAlchemist() - if msg.sender is not the Alchemist
    • MintToZeroAddressError() - if to is the zero address
  • Emits - ERC721 Transfer(address(0), to, tokenId)
burn(uint256 tokenId)
  • Description - Burns a position NFT, permanently destroying it. Used by the Alchemist when a position is fully closed.
    • @param tokenId - The token ID of the position to burn.
  • Visibility Specifier - public
  • State Mutability Specifier - nonpayable
  • Reverts
    • CallerNotAlchemist() - if msg.sender is not the Alchemist
  • Emits - ERC721 Transfer(owner, address(0), tokenId)

Admin Actions​

Functions that can only be called by the current admin.

setMetadataRenderer(address renderer)
  • Description - Sets or updates the external contract used to generate tokenURI metadata for position NFTs.
    • @param renderer - The address of the new metadata renderer contract.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Reverts
    • CallerNotAdmin() - if msg.sender is not the admin
  • Emits - none
setAdmin(address newAdmin)
  • Description - Transfers admin rights to a new address. Unlike other contracts in the protocol, this is a single-step transfer with no pending/accept pattern.
    • @param newAdmin - The address of the new admin.
  • Visibility Specifier - external
  • State Mutability Specifier - nonpayable
  • Reverts
    • CallerNotAdmin() - if msg.sender is not the admin
  • Emits - none

Internal Operations​

_update(address to, uint256 tokenId, address auth)
  • Description - Override of the ERC721 transfer hook that runs before every token transfer. When a position NFT is transferred (not during minting), this calls alchemist.resetMintAllowances(tokenId) to clear all mint allowances on that position. This prevents a previous owner's approved minters from borrowing against the position after it changes hands.
    • @param to - The address receiving the token.
    • @param tokenId - The token ID being transferred.
    • @param auth - The address authorized to perform the transfer.
  • Visibility Specifier - internal
  • State Mutability Specifier - nonpayable
  • Returns - address - the previous owner of the token.

Reading State​

tokenURI(uint256 tokenId)
  • Description - Returns the token URI containing embedded SVG metadata for a position NFT. Delegates to the external metadataRenderer contract.
    • @param tokenId - The token ID to get the URI for.
  • Visibility Specifier - public
  • State Mutability Specifier - view
  • Returns - string memory - the full token URI with embedded metadata.
  • Reverts
    • If the token does not exist (standard ERC721 revert)
    • MetadataRendererNotSet() - if metadataRenderer is the zero address

Errors​

  • CallerNotAlchemist() - Reverts when a function restricted to the Alchemist contract is called by any other address.
  • CallerNotAdmin() - Reverts when a function restricted to the admin is called by any other address.
  • AlchemistZeroAddressError() - Reverts during construction if the Alchemist address is the zero address.
  • MintToZeroAddressError() - Reverts when attempting to mint a position NFT to the zero address.
  • MetadataRendererNotSet() - Reverts when tokenURI is called but no metadata renderer has been set.