Skip to content

Trigger the Public Allocator

The PublicAllocator will be automatically triggered by the Morpho Interface if there is insufficient liquidity to facilitate a borrowing transaction. Here is how to do it manually or programmaticaly:

Using Etherscan

This section explains how to manually trigger the PublicAllocator contract without going through Morpho's interface.

Prerequisites

  1. Verify that the PublicAllocator contract has the Allocator role on the vault you are expecting to reallocate liquidity from.
  2. Ensure that the vault has specified maxOut and maxIn limits for the markets from which you intend to reallocate liquidity:
    • maxOut is the maximum amount of tokens that can be withdrawn from a specific market.
    • maxIn is the maximum amount of tokens that can be supplied to a specific market.
  3. Order the withdrawals tuples in alphabetical order by market id.
  4. Retrieve the fee that the vault owner set up on the PublicAllocator readme section of the contract by simply pasting the vault address.

Make sure to have the following information:

  • fee in ETH,
  • vault address,
  • withdrawals tuples,
  • supplyMarketParams tuple.

Trigger the PublicAllocator

Using the Morpho API

The following section provides tips and guidance for developers who want to programmatically trigger the Public Allocator using the API.

Key Aspects

When using the API script to trigger the Public Allocator, keep in mind the following important aspects:

  1. Buffer for Simulation: The script adds a 0.1% buffer to withdrawal amounts to account for latency in the Public Allocator data (which has a 1-minute update interval).

    // From the script:
    amount: (BigInt(item.assets) * BigInt(999)) / BigInt(1000);
  2. Individual Simulations: The script first simulates each withdrawal individually to validate which ones will succeed before attempting to combine them. This helps identify which vaults and markets can successfully provide liquidity.

  3. Withdrawal Processing: Not all available withdrawals are processed - the script only uses as many as needed to fulfill the requested liquidity amount. If multiple vaults are available, it will try to fulfill the request efficiently.

  4. Transaction Validation: After simulating individual withdrawals, the script attempts a final transaction simulation combining all the successful withdrawals to ensure the transaction will succeed.

  5. Market Liquidity Check: The script first checks if the current market already has enough liquidity for the requested amount. If it does, no reallocation is needed.

    if (liquidityToBeBorrowed < currentMarketLiquidity) {
      console.log(
        "No transactions generated as there is enough liquidity in market."
      );
      return;
    }
  6. Sorting Withdrawals: When constructing the final transaction, withdrawals are sorted by market ID to match the contract's expectations.

    processedWithdrawals[vaultAddress].sort((a, b) =>
      getMarketId(a.marketParams).localeCompare(getMarketId(b.marketParams))
    );

Required Information

To use the API effectively, you'll need:

  1. The chain ID (supports Mainnet and Base)
  2. The target market ID where borrowers will be borrowing from
  3. The amount of liquidity you want to move into the market (in native units)

Example Usage

// Example: Reallocate 20M USDC on Base
const chainId = 8453; // Base chain
const marketId =
  "0x9103c3b4e834476c9a62ea009ba2c884ee42e94e6e314a26f04d312434191836";
const requestedLiquidityNativeUnits = 20000000; // 20M USDC
 
// Trigger the reallocation
reallocateRequestedLiquidity(marketId, chainId, requestedLiquidityNativeUnits);

Error Handling

The script provides detailed error logging for:

  • Failed individual simulations
  • Failed final transaction simulation
  • Insufficient available liquidity to match the requested amount

Environment Setup

Make sure to set up your environment variables for RPC endpoints:

  • RPC_URL_MAINNET for Ethereum Mainnet
  • RPC_URL_BASE for Base

Monitoring and Validation

The script outputs detailed information about:

  • Available liquidity across vaults
  • Successful and failed simulations
  • A comprehensive validation table showing both API data and simulation results
  • A detailed summary of the reallocation across vaults

Using the Morpho SDKs

Here is a tutorial of how to use the SDKs to trigger the public allocator in typescript: