Truebasis

System Concept

Truebasis was created to address a primary challenge in Web3 financial tracking: the accurate calculation of token cost basis and unrealized capital gains. Rather than relying on simple snapshot balances, Truebasis reconstructs a precise double-entry transaction ledger chronologically from address histories, determining cost-basis using First-In, First-Out (FIFO) tax rules.

Truebasis dynamic portfolio tracker: showcasing currency conversions, aggregated address balances, and tax lot breakdown cards.

The system is built as a polyglot microservice architecture. A high-performance Go daemon leverages go-ethereum (Geth) to maintain live WebSocket subscriptions to EVM nodes, decode raw ABI event topics, stream structured transactions into Redis, and expose a gRPC control plane for historical block range queries. The NestJS backend consumes these event streams, manages double-entry MongoDB journal entries, and handles JWT auth, while the Next.js frontend delivers a responsive real-time portfolio dashboard.

Go EVM RPC Indexer & gRPC Control Plane

Blockchain network I/O is inherently high-concurrency and data-intensive. Rather than overloading the Node.js event loop with persistent raw socket parsing and binary ABI log unpacking, I extracted the blockchain telemetry layer into a standalone Go microservice using go-ethereum (Geth).

FIFO Replay Engine

Truebasis determines cost basis dynamically by chronological transaction-ledger replay instead of static balance points. During synchronization, the core engine processes address histories, filters spam or airdrop scam tokens, and replays each transfer in block order.

When an inbound credit is processed, the engine pushes a new lot onto an in-memory FIFO stack, storing the precise quantity, unit price, date, and transaction hash. Outbound debits consume lots from the bottom of the stack (oldest first). If an outbound transfer targets another user-owned wallet, the engine performs a cost-basis preservation split, replicating the consumed lot in the recipient's wallet at its original acquisition price.

DeFi Position Modeling

Tracking DeFi positions (staking pools, yield aggregators, and AMM pools) requires decomposing complex tokens. Truebasis monitors rebasing stakes (like stETH) and reward-bearing tokens (like rETH) to update quantities dynamically. Interest harvested from lending positions is integrated as zero-cost CREDIT entries, updating the average cost basis automatically.

Liquidity pools are modeled dynamically. Depositing tokens into a pool is recorded as a trade (SWAP) of constituent assets for LP shares. Redeeming is mapped as a debit of the LP tokens and credit of the returned tokens, calculating gains or losses against the LP share acquisition cost.

Web3 Auth Roadmap (SIWE)

To supplement standard email and GitHub OAuth credentials, the integration spec introduces Sign-In with Ethereum (SIWE - ERC-4361). This provides cryptographic session authentication, letting users sign in securely via browser-injected private keys.

Closing Thoughts

Truebasis serves as a robust foundation for automated tax lot accounting and real-time blockchain telemetry. The combination of Go for low-level EVM indexing and TypeScript for rich ledger modeling showcases a production-ready polyglot architecture.