DOCSEARCHbyAlgolia
Submit Docs

Aave Utilities SDK

repository·master·Indexed 41 days ago

https://github.com/aave/aave-utilities

A JavaScript SDK built on ethers.js v5 for interacting with Aave V2 and V3. It includes @aave/contract-helpers for generating transactions and querying on-chain data via services like UiPoolDataProvider and UiIncentiveDataProvider, and @aave/math-utils for formatting raw protocol data into human-readable summaries. Note: This repository is deprecated; users are encouraged to refer to aave-sdk.

Tokens
77.9K
Snippets
276
Records
321
Agent score
50%

What's inside Aave Utilities

  1. Initialize PoolBundle and LendingPoolBundle

    master

    New transaction methods are accessed via PoolBundle (for V3) and LendingPoolBundle (for V2) objects. These objects require an ethers provider and a configuration object containing the market's POOL and WETH_GATEWAY addresses.

    To initialize them, use the addresses provided by @bgd-labs/aave-address-book.

    const { PoolBundle, LendingPoolBundle } = require("@aave/contract-helpers");
const markets = require("@bgd-labs/aave-address-book");

// For V3
const poolBundle = new PoolBundle(provider, {
  POOL: markets[marketKey].POOL,
  WETH_GATEWAY: markets[marketKey].WETH_GATEWAY,
});

// For V2
const poolBundle = new LendingPoolBundle(provider, {
  LENDING_POOL: markets[marketKey].POOL,
  WETH_GATEWAY: markets[marketKey].WETH_GATEWAY,
});

  3. Install @aave/math-utils

    master

    Install the @aave/math-utils package into your project using npm or yarn. This package provides data formatting methods that act as a layer on top of raw chain data, supporting use-cases from human-readable formatting to approximating accrual over time.

    // with npm
npm install @aave/math-utils

// with yarn
yarn add @aave/math-utils

  4. Submit transactions generated by the Aave SDK

    master

    The transaction methods in the Aave SDK return an array of transaction objects of type EthereumTransactionTypeExtended from @aave/contract-helpers.

    Note on Approvals: If a protocol interaction requires an approval, the method will return an array containing two transactions (the approval and the interaction). If no approval is needed, it returns a single transaction.

    To execute these transactions using ethers.js, you must extract the transaction data and use a signer (wallet provider) to send the transaction. If the transaction includes a value, it must be converted to a BigNumber.

    import { BigNumber, providers } from 'ethers';
import { EthereumTransactionTypeExtended } from '@aave/contract-helpers';

async function submitTransaction({
  provider, // ethers.providers.Web3Provider
  tx
}: {
  provider: providers.Web3Provider,
  tx: EthereumTransactionTypeExtended
}) {
  const extendedTxData = await tx.tx();
  const { from, ...txData } = extendedTxData;
  const signer = provider.getSigner(from);
  
  const txResponse = await signer.sendTransaction({
    ...txData,
    value: txData.value ? BigNumber.from(txData.value) : undefined,
  });
}

  5. Use ERC-20 Permit for gasless approvals in V3

    master

    If a token supports ERC-2612, you can avoid a separate approve transaction by using a signature-based approach.

    1. Call signERC20Approval to generate the raw signature data.
    2. Trigger a signature request from the user's wallet (e.g., using eth_signTypedData_v4).
    3. Pass the resulting signature to supplyWithPermit or repayWithPermit.
    import { Pool } from '@aave/contract-helpers';

const pool = new Pool(provider, {
  POOL: poolAddress,
  WETH_GATEWAY: wethGatewayAddress,
});

const dataToSign: string = await pool.signERC20Approval({
  user,
  reserve,
  amount,
  deadline,
});

const signature = await provider.send('eth_signTypedData_v4', [
  currentAccount,
  dataToSign,
]);

// Use this signature in pool.supplyWithPermet({ ..., signature, ... })

  6. Initialize Data Provider services

    master

    To fetch Aave protocol data, you must initialize service instances using an ethers provider. The two main services are:

    • UiPoolDataProvider: Used for querying reserve and user data.
    • UiIncentiveDataProvider: Used for querying reward emissions and user claimable rewards.

    It is recommended to use the @bgd-labs/aave-address-book package to import correct contract addresses for your target chain.

    import { ethers } from 'ethers';
import { 
  UiPoolDataProvider, 
  UiIncentiveDataProvider, 
  ChainId 
} from '@aave/contract-helpers';
import * as markets from '@bgd-labs/aave-address-book';

const provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');
const currentAccount = '0x...';

const poolDataProviderContract = new UiPoolDataProvider({
  uiPoolDataProviderAddress: markets.AaveV3Ethereum.UI_POOL_DATA_PROVIDER,
  provider,
  chainId: ChainId.mainnet,
});

const incentiveDataProviderContract = new UiIncentiveDataProvider({
  uiIncentiveDataProviderAddress: markets.AaveV3Ethereum.UI_INCENTIVE_DATA_PROVIDER,
  provider,
  chainId: ChainId.mainnet,
});

  7. Install Aave Utilities via npm or yarn

    master

    Aave Utilities consists of two primary npm packages:

    • @aave/math-utils: Contains methods for formatting raw contract data for frontend usage.
    • @aave/contract-helpers: Contains methods for generating transactions and reading/writing data on protocol contracts.

    Note: This repository is deprecated. Refer to aave-sdk and the official Aave Docs for the latest integration endpoints.

    // with npm
npm install @aave/contract-helpers @aave/math-utils

// with yarn
yarn add @aave/contract-helpers @aave/math-utils

  8. Setup for New Transaction Methods

    master

    To use the new transaction building methods in @aave/contract-helpers, you need to install the helper package along with @bgd-labs/aave-address-book for market addresses and ethers@5 for provider and big number handling.

    npm i @aave/contract-helpers @bgd-labs/aave-address-book ethers@5

  10. Access Aave contract helpers and services

    master

    The @aave/contract-helpers package provides a comprehensive suite of contract wrappers and data providers for interacting with Aave protocols (including V3). Key modules include:

    Core Contract Wrappers

    • Pool/Lending Pool: lendingPool-contract, v3-pool-contract, and bundled versions like lendingPool-contract-bundle or v3-pool-contract-bundle.
    • Staking: staking-contract and V3-uiStakeDataProvider-contract.
    • Governance: governance-contract, governance-power-delegation-contract, and specialized V3 helpers like governance-data-helper and voting-machine-data-helper.
    • ERC20: erc20-contract and erc20-2612 (for Permit-based tokens).

    Data Providers & Services

    • UI Data Providers: v3-UiIncentiveDataProvider-contract and v3-UiPoolDataProvider-contract for fetching data optimized for frontend consumption.
    • Incentives: incentive-controller and incentive-controller-v2.
    • Wallet/Balance: wallet-balance-provider.

    Permissions

    • Access PERMISSION constants and PERMISSION_MAP via the permissions-manager module to handle authorization logic.

  11. How V3MigrationHelperService handles signed permits

    master

    The V3MigrationHelperService supports using signed EIP-712 permits to reduce the number of on-chain transactions required for migration.

    When signedSupplyPermits or signedCreditDelegationPermits are provided in the migrate call:

    1. The service uses splitSignedPermits or splitSignedCreditDelegationPermits to decompose the signed messages into their v, r, s components.
    2. These components are passed directly to the migrate function on the smart contract.
    3. If these permits are present, the service skips generating manual approve or approveDelegation transactions, significantly reducing gas costs and transaction count for the user.

  12. WrappedTokenGatewayV3: CallStatic, EstimateGas, and PopulateTransaction

    master

    For every state-changing method in WrappedTokenGatewayV3, the following helper objects are available to facilitate advanced ethers.js workflows:

    • callStatic: Simulates the transaction locally without sending it. Returns a Promise<void> (or the return value of the function) instead of a ContractTransaction. Use this to check if a transaction will revert before sending.
    • estimateGas: Returns a Promise<BigNumber> representing the estimated gas required for the transaction.
    • populateTransaction: Returns a Promise<PopulatedTransaction>, allowing you to manually construct and sign the transaction object before sending it via a provider.