Truebasis

Truebasis
RoleCreator & Lead Architect
PeriodApr 2026 — Jun 2026
TechNext.js 16, NestJS, MongoDB, Redis, Hardhat
Cool Links-
LocationRemote
Company Websitetruebasis repository ↗

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 Portfolio Dashboard Interface
Truebasis dynamic portfolio tracker: showcasing currency conversions, aggregated address balances, and tax lot breakdown cards.

The project is structured around a decoupled architecture. The NestJS backend manages blockchain transaction ingestion, ledger reconstruction, caching, and rate limiting. The Next.js frontend delivers a premium responsive dashboard showcasing detailed asset breakdown tables, wallet grouping cards, and active tax-lot positions.

System Infrastructure Stack
Frontend Web AppNext.js 16 (App Router)Interfaces with NestJS using React Query & Axios. Features wallet filter sliders, currency conversions, and responsive grouped grids.
Backend API NodeNestJS & MongoDB (Mongoose)Exposes REST APIs, verifies Passport JWT credentials, parses database entities, and triggers ledger sync loops.
Queue BrokerRedis & BullMQHandles heavy address synchronization background jobs asynchronously, managing rate-limit retries and API cooldown locks.
Simulated TestnetHardhat Network EVM nodeSeeds simulated transactions, staking yields, and LP swaps locally, generating deterministic Zerion mock dumps.

FIFO Replay Engine

Truebasis determines cost basis dynamically by chronological transaction-ledger replay instead of static balance points. During synchronization, the core engine fetches address histories from Zerion, 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.

FIFO Transaction Replay Pipeline
Genesis SyncDeletes existing lots → Replays historical ledger in mined order → Saves lastSyncAt
IncrementalFilters transactions mined after lastSyncAt → Appends updates in real-time
Replica SplitMatches internal transfers → Backfills credit with sender's cost & date

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.

1. Challenge NonceGET /auth/nonceGenerates a random, time-sensitive cryptographic string on the server to prevent replay attacks.
2. EIP-191 SignaturesignMessage()Requests private key cryptographic signature of the formatted SIWE challenge in the browser.
3. Verification JWTPOST /auth/verifyBackend verifies signature using ECRecover, fetches user address, and returns a secure JWT token.

Interactive FIFO Sandbox

Interact with the live simulator below to explore the core FIFO replay engine and cryptographic SIWE flow in real-time. Toggle between tabs, add manual buys/sells/transfers, and trigger step-by-step walk-throughs to see how lots are processed.

Truebasis Interactive Ledger SandboxSimulate cryptocurrency database ledgers, FIFO lot stack adjustments, and Web3 cryptographic signature flows.
Asset Balance0.00 ETH
Net Worth (Current)$0.00
Total Cost Basis$0.00
Unrealized Profit/Loss$0.00(0.0%)
Replay Walkthrough (FIFO Engine)
Manual Transaction Input
Active Cost-Basis Lots StackFIFO Queue (Bottom-first consumption)
No active tax lots found. Run Genesis Sync to build the database lot queue.
FIFO Ledger Event Replay Stream

Milestones

NestJS Modular Backend API Setup|Backend

Apr 2026

Genesis Sync & FIFO Stack Rebuild Engine|Backend/Database

May 2026

Dynamic DeFi Staking & LP Calculation|Protocol API

May 2026

Hardhat Ethers Simulation Harness Deploy|Simulation

Jun 2026

Interactive Next.js Dashboard Frontend|Frontend/Design

Jun 2026

Closing Thoughts

Truebasis serves as a robust foundation for automated tax lot accounting. The roadmap includes implementing the Sign-In with Ethereum (SIWE) standard for cryptographic credentials, enabling users to log in directly via browser extension private keys.

←Back to Work