Crypto fund position accounting system

Development of Crypto Fund Position Accounting Systems

Accounting for crypto fund positions isn't "check the balance on etherscan". It's a multidimensional task: positions distributed across dozens of wallets and multiple blockchains, significant portions locked in DeFi protocols, derivatives values change nonlinearly, and all must be aggregated in real-time with correct P&L calculation and historical cost accounting for tax reporting.

Turnkey solutions like Zapper or DeBank are fine for individuals. For a fund with custodial requirements, audit, and custom calculation methodology — a custom system is needed.

System architecture

The system consists of four layers:

Data Layer:    Blockchain Nodes / RPC Providers
               ↓
Indexing:      Position Fetchers (per protocol)
               ↓
Accounting:    Valuation Engine + P&L Calculator
               ↓
Reporting:     API + Dashboard + Audit Export

Data Layer: data sources

Each position type needs different sources:

Spot holdings (tokens on wallets): eth_call to ERC-20 balanceOf or aggregation via Moralis/Alchemy getTokenBalances. For multi-chain — parallel requests to each chain.

DeFi positions — most complex. Each protocol has its own model:

Locked/vested positions: vesting contracts, gauge locks (Curve/Velodrome veNFT), staking with lockup. These have future value with time discount — need to decide how to account for them in NAV.

Position Fetcher: abstraction layer

Each protocol implements a PositionFetcher interface:

interface Position {
    protocol: string
    chain: string
    type: 'spot' | 'lp' | 'lending' | 'borrowing' | 'staking' | 'perp'
    tokens: TokenAmount[]    // position components
    valueUsd: Decimal        // current value
    metadata: Record<string, unknown>
}

interface PositionFetcher {
    protocol: string
    chains: string[]
    fetch(wallet: string, blockNumber?: number): Promise<Position[]>
}

Example Uniswap V3 fetcher:

class UniswapV3Fetcher implements PositionFetcher {
    protocol = 'uniswap-v3'
    chains = ['ethereum', 'arbitrum', 'optimism', 'polygon', 'base']

    async fetch(wallet: string, blockNumber?: number): Promise<Position[]> {
        const nfpm = new ethers.Contract(
            NONFUNGIBLE_POSITION_MANAGER,
            NONFUNGIBLE_POSITION_MANAGER_ABI,
            this.provider
        )
        const overrides = blockNumber ? { blockTag: blockNumber } : {}

        // Get all LP NFTs via Transfer events (genesis to now)
        const balance = await nfpm.balanceOf(wallet, overrides)
        const tokenIds = await Promise.all(
            Array.from({ length: Number(balance) }, (_, i) =>
                nfpm.tokenOfOwnerByIndex(wallet, i, overrides)
            )
        )

        const positions = await Promise.all(
            tokenIds.map(async (id) => {
                const pos = await nfpm.positions(id, overrides)
                return this.decodePosition(id, pos, wallet, blockNumber)
            })
        )

        return positions.filter(p => p.tokens[0].amount > 0n || p.tokens[1].amount > 0n)
    }

    private async decodePosition(
        tokenId: bigint,
        pos: UniswapV3PositionStruct,
        wallet: string,
        blockNumber?: number
    ): Promise<Position> {
        // Calculate amounts from liquidity + tickLower + tickUpper + currentSqrtPriceX96
        const [token0Amount, token1Amount] = getAmountsForLiquidity(
            await this.getCurrentSqrtPrice(pos.poolAddress, blockNumber),
            pos.tickLower,
            pos.tickUpper,
            pos.liquidity
        )

        // Accumulated fees (unclaimed)
        const [fees0, fees1] = await this.getUnclaimedFees(tokenId, blockNumber)

        return {
            protocol: 'uniswap-v3',
            chain: this.chain,
            type: 'lp',
            tokens: [
                { token: pos.token0, amount: token0Amount + fees0 },
                { token: pos.token1, amount: token1Amount + fees1 },
            ],
            valueUsd: await this.calculateUsdValue(pos.token0, token0Amount, pos.token1, token1Amount),
            metadata: { tokenId: tokenId.toString(), fee: pos.fee, tickRange: [pos.tickLower, pos.tickUpper] },
        }
    }
}

Valuation (Valuation Engine)

Price sources

For accurate valuation, need a hierarchy of price sources:

1. DEX on-chain price (Uniswap V3 TWAP) — manipulable at short windows, reliable at 30-minute TWAP
2. CEX aggregator (CoinGecko, CoinMarketCap API) — up to 5 minute delay, unavailable for exotics
3. Pyth Network / Chainlink — on-chain oracle, for positions already on-chain
4. Manual pricing — for illiquid tokens, OTC positions

class ValuationEngine {
    private priceCache = new Map<string, { price: Decimal; timestamp: number }>()

    async getPrice(tokenAddress: string, chain: string): Promise<Decimal> {
        const cacheKey = `${chain}:${tokenAddress}`
        const cached = this.priceCache.get(cacheKey)

        // Cache for 60 seconds during active market hours
        if (cached && Date.now() - cached.timestamp < 60_000) {
            return cached.price
        }

        const price = await this.fetchPriceWithFallback(tokenAddress, chain)
        this.priceCache.set(cacheKey, { price, timestamp: Date.now() })
        return price
    }

    private async fetchPriceWithFallback(token: string, chain: string): Promise<Decimal> {
        // 1. Try Uniswap V3 TWAP (30 min)
        try {
            return await this.getUniswapTWAP(token, chain, 1800)
        } catch {}

        // 2. CoinGecko API
        try {
            return await this.getCoinGeckoPrice(token, chain)
        } catch {}

        // 3. Last known price from DB marked stale
        const lastKnown = await this.db.getLastKnownPrice(token, chain)
        if (lastKnown) {
            this.emitAlert(`STALE_PRICE: ${token} on ${chain}`)
            return lastKnown.price
        }

        throw new Error(`Cannot price token ${token} on ${chain}`)
    }
}

Rebasing tokens

Special case: rebasing tokens — stETH, aUSDC, aETH. Their balance changes each block without Transfer events. Either account for actual balance via balanceOf instead of Transfer-based accounting, or convert to wrapped version (wstETH instead of stETH).

P&L calculation and cost basis

For tax reporting and performance reporting, need to track historical position values. Two main methods:

FIFO (First In, First Out) — for each sale, take cost of earliest purchased portion. Requires full acquisition history.

Average Cost Basis — average cost of all purchased tokens. Simpler to calculate, less tax-efficient in rising markets.

class CostBasisTracker {
    // Lots: each purchase is separate lot with date and price
    async recordAcquisition(
        wallet: string,
        token: string,
        amount: Decimal,
        priceUsd: Decimal,
        txHash: string,
        timestamp: Date
    ): Promise<void> {
        await this.db.query(`
            INSERT INTO cost_basis_lots
                (wallet, token, amount, price_usd, cost_basis_usd, acquired_at, tx_hash)
            VALUES ($1, $2, $3, $4, $3 * $4, $5, $6)
        `, [wallet, token, amount, priceUsd, timestamp, txHash])
    }

    async calculateRealizedPnl(
        wallet: string,
        token: string,
        soldAmount: Decimal,
        soldPriceUsd: Decimal
    ): Promise<{ realizedPnl: Decimal; costBasis: Decimal }> {
        // FIFO: take lots in acquisition order
        const lots = await this.db.query(`
            SELECT id, amount, price_usd
            FROM cost_basis_lots
            WHERE wallet = $1 AND token = $2 AND remaining_amount > 0
            ORDER BY acquired_at ASC
        `, [wallet, token])

        let remaining = soldAmount
        let totalCostBasis = new Decimal(0)

        for (const lot of lots.rows) {
            if (remaining.lte(0)) break
            const consumed = Decimal.min(remaining, new Decimal(lot.remaining_amount))
            totalCostBasis = totalCostBasis.plus(consumed.mul(lot.price_usd))
            remaining = remaining.minus(consumed)
            await this.updateLotRemainder(lot.id, consumed)
        }

        const proceeds = soldAmount.mul(soldPriceUsd)
        return {
            realizedPnl: proceeds.minus(totalCostBasis),
            costBasis: totalCostBasis,
        }
    }
}

Snapshots and historical NAV

For audit and investor reporting, need historical snapshots. System should be able to recreate portfolio at any historical date:

CREATE TABLE portfolio_snapshots (
    id              BIGSERIAL PRIMARY KEY,
    snapshot_at     TIMESTAMPTZ NOT NULL,
    wallet          VARCHAR(42) NOT NULL,
    block_number    BIGINT NOT NULL,  -- anchor to specific block
    total_value_usd NUMERIC(20, 6) NOT NULL,
    positions       JSONB NOT NULL,   -- serialized position list
    prices_used     JSONB NOT NULL    -- prices used for valuation
);

-- Index for fast NAV period lookup
CREATE INDEX idx_snapshots_wallet_time
ON portfolio_snapshots (wallet, snapshot_at DESC);

Historical block snapshot requires archive node (or provider with archive access). Alchemy and QuickNode provide historical state via eth_call with blockTag.

Alerts and operational monitoring

Position accounting system without alerts is one nobody checks. Required triggers:

• Position change > N% in 15 minutes (unexpected activity)
• Token price unavailable > 5 minutes (STALE_PRICE)
• Discrepancy between on-chain balance and accounting > 0.1%
• Liquidation in lending protocol
• Uniswap V3 position out of range

Stack: Node.js / Go backend, PostgreSQL with TimescaleDB, Redis for price cache, Grafana dashboard, PagerDuty for critical alerts. Archive RPC via Alchemy/QuickNode for historical data.