DeFi Llama
  • List your project
    • DefiLlama and our methodology
    • How to list a DeFi project
    • How to add a new Blockchain
    • How to write an SDK adapter
    • Functions we've written so you don't have to
      • Staking and Pool2
      • Fork helpers
      • General EVM contract calls
    • What to include as TVL?
    • How to update a project
    • How to write dimensions adapters
    • Emissions dashboard
      • Protocol Files
      • Emission Sections
      • Testing
    • Oracles TVS
  • analysts
    • Data Definitions
  • Chainlist
    • How to change Ethereum's RPC
    • Add a new RPC endpoint
  • FAQs
    • Frequently Asked Questions
  • Coin Prices API
  • Pricing
Powered by GitBook
On this page
  • Helper Functions
  • Token Tracking Helpers
  • EVM Data Helpers
  • Protocol-Specific Helpers
  • Query Engine Helpers
  • Chain-Specific Helpers
  • Helper Function Reference

Was this helpful?

  1. List your project
  2. How to write dimensions adapters

Helper functions

Last updated 9 days ago

Was this helpful?

Note (Updated: 2025-05-01): This page might contain outdated information. For the most up-to-date documentation, please visit the main guide.

Helper Functions

This document provides detailed information about the various helper functions available to simplify the creation of adapters. Each section includes example implementations and links to real adapters using these functions.

Token Tracking Helpers

addTokensReceived

Tracks ERC20 token transfers received by specified addresses. Supports filtering by sender/receiver and custom token transformations. It attempts to use an indexer first for performance, with a fallback to log processing.

import { addTokensReceived } from '../../helpers/token';

const fetch: any = async (options: FetchOptions) => {
  const dailyFees = await addTokensReceived({
    options,
    tokens: ["0x4200000000000000000000000000000000000006"], // WETH on Base
    targets: ["0xbcb4a982d3c2786e69a0fdc0f0c4f2db1a04e875"] // Treasury
  })

  return { dailyFees, dailyRevenue: dailyFees }
}

addGasTokensReceived

Tracks native token transfers (like ETH) received by specified multisig addresses. This helper is particularly useful for protocols that collect fees in the chain's native token.

import { addGasTokensReceived } from '../../helpers/token';

const fetch = async (options: FetchOptions) => {
  const dailyFees = await addGasTokensReceived({
    options,
    multisigs: ["0x123...abc", "0x456...def"] // Treasury multisig addresses
  });
  
  return { dailyFees, dailyRevenue: dailyFees };
}

getETHReceived

Tracks native token transfers on EVM chains, supporting multiple chains through Allium database queries.

import { getETHReceived } from '../../helpers/token';

const fetch = async (options: FetchOptions) => {
  const balances = options.createBalances();
  await getETHReceived({
    options,
    balances,
    target: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" // Treasury address
  });
  
  return { dailyFees: balances, dailyRevenue: balances };
}

getSolanaReceived

Fetches token transfers to specified Solana addresses within a given time range, with ability to exclude specific sender addresses or transaction signers.

import { getSolanaReceived } from '../../helpers/token';

const fetch = async (options: FetchOptions) => {
  const dailyFees = options.createBalances();
  await getSolanaReceived({
    options,
    balances: dailyFees,
    target: "9yMwSPk9mrXSN7yDHUuZurAh1sjbJsfpUqjZ7SvVtdco", // Treasury
    blacklists: ["3xxxx..."] // Optional senders to exclude
  });
  
  return { dailyFees, dailyRevenue: dailyFees };
}

EVM Data Helpers

getLogs

Retrieves event logs from blockchains based on specified filters like target addresses, event signatures, and topics. Essential for tracking on-chain events.

const fetch = async ({ getLogs, createBalances }) => {
  const dailyFees = createBalances();
  const logs = await getLogs({
    target: "0xcf205808ed36593aa40a44f10c7f7c2f67d4a4d4",
    eventAbi: 'event Trade(address trader, address subject, bool isBuy, uint256 shareAmount, uint256 ethAmount, uint256 protocolEthAmount, uint256 subjectEthAmount, uint256 supply)'
  });
  
  logs.forEach(log => {
    dailyFees.addGasToken(log.protocolEthAmount);
  });
  
  return { dailyFees };
}

queryIndexer

Executes queries against DeFiLlama's indexers to retrieve token transfers, events, and other blockchain data.

import { queryIndexer } from '../../helpers/indexer';

const fetch = async (options: FetchOptions) => {
  const transfers = await queryIndexer({
    chain: options.chain,
    fromTimestamp: options.startTimestamp, 
    toTimestamp: options.endTimestamp,
    filter: { to: "0x123...abc" }
  });
  
  const dailyFees = options.createBalances();
  transfers.forEach(t => dailyFees.add(t.token, t.value));
  
  return { dailyFees };
}

Protocol-Specific Helpers

compoundV2Export

Creates an adapter for Compound V2-like protocols, taking config parameters and returning an object that tracks fees, revenue, and distribution among holders and suppliers.

import { compoundV2Export } from '../helpers/compound';

export default compoundV2Export({
  reserveFactor: 0.1, // 10% of interest goes to protocol
  markets: {
    [CHAIN.ETHEREUM]: {
      comptroller: '0x123...abc',
      // ... other market parameters
    }
  }
});

uniV2Exports / getUniV2LogAdapter

Generates adapter configurations for Uniswap V2-style DEXes across multiple chains.

import { uniV2Exports } from '../helpers/uniswap';

export default uniV2Exports({
  [CHAIN.BSC]: {
    factories: [
      '0x123...abc' // Factory address
    ],
    fees: {
      type: 'fixed',
      feesPercentage: 0.3 // 0.3% fee
    }
  },
  // Other chains
});

uniV3Exports

Creates adapters for Uniswap V3-style DEXes, supporting variable fees and multiple pools.

import { uniV3Exports } from '../helpers/uniswap';

export default uniV3Exports({
  [CHAIN.ETHEREUM]: {
    factory: '0x1F98431c8aD98523631AE4a59f267346ea31F984',
    // Optional custom fee handling or additional configurations
  }
});

Query Engine Helpers

queryDuneSql

Executes SQL queries against the Dune Analytics database.

import { queryDuneSql } from '../helpers/dune';

const fetch = async (options: FetchOptions) => {
  const results = await queryDuneSql(
    options,
    `SELECT SUM(fee_amount) as fees
    FROM ethereum.transactions
    WHERE to = '0x123...abc'
    AND block_time BETWEEN to_timestamp(${options.startTimestamp}) AND to_timestamp(${options.endTimestamp})`
  );
  
  const dailyFees = options.createBalances();
  dailyFees.addGasToken(results[0].fees);
  
  return { dailyFees };
}

queryAllium

Queries the Allium database for blockchain data across multiple chains.

import { queryAllium } from '../helpers/allium';

const fetch = async (options: FetchOptions) => {
  const result = await queryAllium(`
    SELECT SUM(value) as revenue
    FROM ethereum.transactions
    WHERE to_address = '0x123...abc'
    AND block_timestamp BETWEEN TO_TIMESTAMP_NTZ(${options.startTimestamp}) AND TO_TIMESTAMP_NTZ(${options.endTimestamp})
  `);
  
  const dailyFees = options.createBalances();
  dailyFees.addGasToken(result[0].revenue);
  
  return { dailyFees };
}

getGraphDimensions2

Alternative implementation of getGraphDimensions with a simplified approach for newer adapter versions.

import { getGraphDimensions2 } from '../helpers/getUniSubgraphVolume';

const adapter = getGraphDimensions2({
  graphUrls: {
    [CHAIN.ETHEREUM]: 'https://api.thegraph.com/subgraphs/name/protocol/subgraph',
  },
  feesPercent: 0.3,
  dailyFeeField: 'feesUSD',
  // Additional configuration options
});

Chain-Specific Helpers

fetchTransactionFees

Retrieves the total transaction fees for a specific blockchain network within a given time range.

import { fetchTransactionFees } from '../helpers/chain-fees';

const fetch = async (options: FetchOptions) => {
  const dailyFees = await fetchTransactionFees(options);
  return { dailyFees };
}

Helper Function Reference

You can find the full source code for these helper functions in the DeFi Llama GitHub repository:

Exact day timestamp

Some data sources are only able to return data given a 00:00:00 day timestamp. In that case you can use the parameter startOfDay to get the timestamp of the specific day. For example passing 1663718399 (2022-09-20T23:59:59.000Z) timestamp will return 1663632000000 (2022-09-20T00:00:00.000Z)

- Contains functions like addTokensReceived, getETHReceived, etc.

- Contains uniV2Exports, uniV3Exports

- Contains compoundV2Export

- Contains getGraphDimensions2

Building Dimension Adapters
Example Implementation - Synthetix
Example Implementation - DexTools
Example Implementation - Jito
Example Implementation - Ostium
Example Implementation - Sudoswap V2
Example Implementation - Strike
Example Implementation - Nile Exchange V1
Example Implementation - Hydrometer
Example Implementation - ABCDEFX
Example Implementation - 2thick
Example Implementation - Pumpswap
Example Implementation - Quickswap
Token Helpers
Uniswap Helpers
Compound Helpers
Graph Helpers