Helper functions
Note (Updated: 2025-05-01): This page might contain outdated information. For the most up-to-date documentation, please visit the main Building Dimension Adapters 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 }
}
Example Implementation - Synthetix
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 };
}
Example Implementation - DexTools
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 };
}
Example Implementation - Ostium
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 };
}
Example Implementation - Sudoswap V2
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
}
}
});
Example Implementation - Strike
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
});
Example Implementation - Nile Exchange V1
Example Implementation - Hydrometer
Example Implementation - ABCDEFX
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
}
});
Example Implementation - 2thick
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 };
}
Example Implementation - Pumpswap
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
});
Example Implementation - Quickswap
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 DefiLlama GitHub repository:
Token Helpers - Contains functions like addTokensReceived, getETHReceived, etc.
Uniswap Helpers - Contains uniV2Exports, uniV3Exports
Compound Helpers - Contains compoundV2Export
Graph Helpers - Contains getGraphDimensions2
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)
Last updated
Was this helpful?