Aave V3 Tokenization Contracts

Reference for AToken, RwaAToken, StataTokenFactory and VariableDebtToken.

AToken

aTokens are tokens minted and burned upon supply and withdraw of assets to an Aave market. aTokens denote the amount of crypto assets supplied to the protocol and the yield earned on those assets. The aTokens’ value is pegged to the value of the corresponding supplied asset at a 1:1 ratio and can be safely stored, transferred or traded. All yield collected by the aTokens' reserves are distributed to aToken holders directly by continuously increasing their wallet balance.

This contract is the implementation of the interest bearing token for the Aave Protocol. It inherits the ScaledBalanceTokenBase and EIP712Base token contracts.

All standard ERC-20 methods are implemented for aTokens, such as balanceOf, transfer, transferFrom, approve, totalSupply etc.

balanceOf will always return the most up to date balance of the user, which includes their principal balance and the yield generated by the principal balance.

The source code is available on GitHub.

Write Methods

initialize

function initialize(
    IPool initializingPool,
    address underlyingAsset,
    uint8 aTokenDecimals,
    string calldata aTokenName,
    string calldata aTokenSymbol,
    bytes calldata params
) public virtual

Called when aToken instance is initialized. The treasury and incentives controller are immutable and set in the constructor.

Input Parameters:

mint

function mint(
    address caller,
    address onBehalfOf,
    uint256 scaledAmount,
    uint256 index
) external virtual override onlyPool returns (bool)

Mints aTokens to onBehalfOf.

Input Parameters:

Return Values:

burn

function burn(
    address from,
    address receiverOfUnderlying,
    uint256 amount,
    uint256 scaledAmount,
    uint256 index
) external virtual override onlyPool returns (bool)

Burns aTokens from from and sends the equivalent amount of underlying to receiverOfUnderlying.

In some instances, the mint event could be emitted from a burn transaction if the amount to burn is less than the interest that the user accrued.

Input Parameters:

Return Values:

mintToTreasury

function mintToTreasury(uint256 scaledAmount, uint256 index) external virtual override onlyPool

Mints aTokens to the reserve treasury.

Input Parameters:

transferOnLiquidation

function transferOnLiquidation(
    address from,
    address to,
    uint256 amount,
    uint256 scaledAmount,
    uint256 index
) external virtual override onlyPool

Transfers aTokens in the event of a borrow being liquidated, in case the liquidator reclaims the aToken.

Input Parameters:

transferUnderlyingTo

function transferUnderlyingTo(address target, uint256 amount) external virtual override onlyPool

Transfers the underlying asset to target.

Used by the Pool to transfer assets in borrow(), withdraw() and flashLoan().

Input Parameters:

permit

function permit(
    address owner,
    address spender,
    uint256 value,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external override

Allows a user to permit another account (or contract) to use their funds using a signed message. This enables gas-less transactions and single approval/transfer transactions. Allow passing a signed message to approve spending.

Implements the permit function as for EIP-2612.

Input Parameters:

Example of signing and utilizing permit:

import { Contract, Signature, Wallet, getDefaultProvider } from "ethers";

const signer = new Wallet(process.env.PRIVATE_KEY!, getDefaultProvider());

const aTokenAddress = "ATOKEN_ADDRESS";
const aToken = new Contract(
  aTokenAddress,
  [
    "function name() view returns (string)",
    "function nonces(address owner) view returns (uint256)",
    "function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)",
  ],
  signer
);

const owner = await signer.getAddress();
const spender = "SPENDER_ADDRESS";
const value = 100n;
const nonce = await aToken.nonces(owner);
const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600);

const signature = await signer.signTypedData(
  {
    name: await aToken.name(),
    version: "1",
    chainId: 1,
    verifyingContract: aTokenAddress,
  },
  {
    Permit: [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
      { name: "value", type: "uint256" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
    ],
  },
  { owner, spender, value, nonce, deadline }
);

const { v, r, s } = Signature.from(signature);

await aToken.permit(owner, spender, value, deadline, v, r, s);

rescueTokens

function rescueTokens(
    address token,
    address to,
    uint256 amount
) external override onlyPoolAdmin

Rescue and transfer tokens locked in this contract. Only callable by POOL_ADMIN.

Input Parameters:

View Methods

balanceOf

function balanceOf(address user)
    public
    view
    virtual
    override(IncentivizedERC20, IERC20)
    returns (uint256)

Returns the amount of tokens owned by user.

Overrides the base function.

Input Parameters:

Return Values:

totalSupply

function totalSupply() public view virtual override(IncentivizedERC20, IERC20) returns (uint256)

Returns the amount of tokens in existence.

Overrides the base function.

Return Values:

RESERVE_TREASURY_ADDRESS

function RESERVE_TREASURY_ADDRESS() external view override returns (address)

Returns the address of the Aave treasury, controlled by governance, receiving the fees on this aToken.

Return Values:

UNDERLYING_ASSET_ADDRESS

function UNDERLYING_ASSET_ADDRESS() external view override returns (address)

Returns the address of the underlying reserve asset of this aToken (E.g. WETH for aWETH).

Return Values:

DOMAIN_SEPARATOR

function DOMAIN_SEPARATOR() public view override(IAToken, EIP712Base) returns (bytes32)

Get the domain separator for the token at the current chain.

Return cached value if chainId matches cache, otherwise recomputes separator.

Overrides the base function to fully implement IAToken.

Return Values:

nonces

function nonces(address owner) public view override(IAToken, EIP712Base) returns (uint256)

Returns the nonce value for address specified as parameter. This is the nonce used when calling permit().

Overrides the base function to fully implement IAToken.

Input Parameters:

Return Values:

Example:

const token = new Contract(aTokenAddress, aToken.abi, provider);
await token.nonces(user);

RwaAToken

RwaAToken is a specialized version of the AToken contract designed for Real-World Assets (RWAs). It represents a user’s supplied collateral in the Aave Horizon market. To comply with regulatory requirements, RwaAToken instances are non-transferable by default for end-users.

Key functionalities such as transfer, approve, and permit are disabled to prevent peer-to-peer movement of these tokens. Aave Horizon introduces an ATOKEN_ADMIN_ROLE, which can be granted to RWA issuers or their designated managers to manage functions such as wallet recovery or position migration. An address holding this role can execute authorized transfers on behalf of users, as detailed below.

Write Methods

authorizedTransfer

function authorizedTransfer(address from, address to, uint256 amount) external returns (bool)

Transfers an amount of aTokens between two users. This function can only be called by the RwaATokenManager address holding the ATOKEN_ADMIN_ROLE to granularly manage aToken-specific transfers. It is intended for administrative actions, such as migrating a user’s position to a new wallet. The transfer is still subject to the protocol’s health factor checks.

Input Parameters:

Return Values:

mint

function mint(
    address caller,
    address onBehalfOf,
    uint256 amount,
    uint256 index
) public virtual returns (bool)

Mints amount aTokens to a user. This function overrides the standard mint to enforce that the caller of the transaction must be the same as the onBehalfOf address. This effectively disables the supplyOnBehalfOf functionality for RWAs.

Input Parameters:

Return Values:

Pure Methods

ATOKEN_ADMIN_ROLE

function ATOKEN_ADMIN_ROLE() external pure returns (bytes32)

Returns the bytes32 identifier for the ATOKEN_ADMIN_ROLE. This role grants permission to call authorizedTransfer.

Return Values:

Unsupported Operations

To enforce the non-transferable and compliant nature of RWA collateral, most standard ERC-20 interactions are disabled for RwaAToken. Calling any of the following functions will revert with an OPERATION_NOT_SUPPORTED error:

• permit
• approve
• increaseAllowance
• decreaseAllowance
• transfer
• transferFrom
• mintToTreasury
• transferOnLiquidation
• transferUnderlyingTo

StataTokenFactory

The StataTokenFactory is a factory and registry contract that manages all deployed StataToken instances for a specified Aave pool. It allows deploying new StataToken instances on demand and validates that there is only one StataToken instance per underlying asset. This contract maintains a mapping between underlying assets and their corresponding StataToken addresses.

StataTokens are ERC-4626 compliant tokens that wrap Aave’s aTokens to provide a non-rebasing yield accrual mechanism.

The source code is available on GitHub.

Write Methods

initialize

function initialize() external initializer

Initializes the StataTokenFactory contract. This function is part of the Initializable pattern and is required to initialize the contract after deployment. In this implementation, it does not perform any actions.

createStataTokens

function createStataTokens(address[] memory underlyings) external returns (address[] memory)

Creates new StataToken instances for the given underlying assets if they do not already exist. For each provided underlying asset, the function checks if a StataToken already exists. If it does, the existing StataToken address is returned. If not, it deploys a new StataToken for that underlying asset, registers it, and returns the new address.

Input Parameters:

Return Values:

Emits:

• StataTokenCreated(address indexed stataToken, address indexed underlying) event for each new StataToken created.

Reverts:

• NotListedUnderlying(address underlying) if the underlying asset is not listed in the Aave pool.

View Methods

getStataTokens

function getStataTokens() external view returns (address[] memory)

Returns all StataToken instances deployed via this factory.

Return Values:

getStataToken

function getStataToken(address underlying) external view returns (address)

Returns the StataToken address for a given underlying asset.

Input Parameters:

Return Values:

POOL

function POOL() external view returns (IPool)

Returns the address of the Aave pool associated with this factory.

Return Values:

INITIAL_OWNER

function INITIAL_OWNER() external view returns (address)

Returns the initial owner of the StataToken proxies created by this factory.

Return Values:

TRANSPARENT_PROXY_FACTORY

function TRANSPARENT_PROXY_FACTORY() external view returns (ITransparentProxyFactory)

Returns the address of the transparent proxy factory used for creating new StataToken proxies.

Return Values:

STATA_TOKEN_IMPL

function STATA_TOKEN_IMPL() external view returns (address)

Returns the address of the StataToken implementation used when deploying new StataToken instances.

Return Values:

VariableDebtToken

Implements a variable debt token to track the borrowing positions of users at variable rate mode.

transfer and approve functionalities are disabled as variable debt tokens are non-transferable.

The vToken value is pegged 1:1 to the value of underlying borrowed asset and represents the current total amount owed to the protocol i.e. principal debt + interest accrued.

The VariableDebtToken contract inherits the DebtTokenBase and ScaledBalanceTokenBase token contracts.

The source code is available on GitHub.

Write Methods

initialize

function initialize(
    IPool initializingPool,
    address underlyingAsset,
    uint8 debtTokenDecimals,
    string memory debtTokenName,
    string memory debtTokenSymbol,
    bytes calldata params
) external virtual

Called when variableDebtToken instance is initialized.

Input Parameters:

mint

function mint(
    address user,
    address onBehalfOf,
    uint256 amount,
    uint256 scaledAmount,
    uint256 index
) external virtual override onlyPool returns (uint256)

Mints the variable debt token to the onBehalfOf address.

Input Parameters:

Return Values:

burn

function burn(
    address from,
    uint256 scaledAmount,
    uint256 index
) external virtual override onlyPool returns (bool, uint256)

Burns user variable debt.

In some instances, a burn transaction will emit a mint event if the amount to burn is less than the interest that the user accrued.

Input Parameters:

Return Values:

View Methods

UNDERLYING_ASSET_ADDRESS

function UNDERLYING_ASSET_ADDRESS() external view override returns (address)

Returns the address of the underlying asset of this variableDebtToken (e.g. WETH for variableDebtWETH)

Return Values:

balanceOf

function balanceOf(address account) public view virtual override returns (uint256)

Returns the amount of tokens owned by account - the most up to date accumulated debt (principal + interest) of the user.

Standard ERC-20 function.

Input Parameters:

Return Values:

totalSupply

function totalSupply() public view virtual override returns (uint256)

Returns the amount of tokens in existence - the most up to date total debt accrued by all protocol users for that specific variable rate of debt token.

Standard ERC-20 function.

Return Values:

Unsupported Operations

Being non-transferable, the variable debt token does not implement any of the standard ERC-20 functions for transfer and allowance.

The following functions revert with OperationNotSupported(): transfer, allowance, approve, transferFrom, renounceAllowance, increaseAllowance, decreaseAllowance.