Protocol Design

TaxChain is architected as a layer-zero compliance fabric that spans on-chain smart-contract components, off-chain verifiable compute, and a cryptographically linked data-availability layer. The guiding design principles are:

  1. Determinism – Every identical input must produce an identical output, independent of node topology.

  2. Auditability – Each step in the pipeline commits a verifiable hash to a public chain so external parties can replay or challenge results.

  3. Modularity – All moving parts (indexers, classifiers, rulebooks, report compilers, gateways) are hot-swappable, version-pinned, and upgradable without breaking historical proofs.

  4. Minimal Trust – Private data never leaves user-controlled encryption domains; all cross-module messages are authenticated and tamper-evident.

  5. Horizontal Scalability – The system must sustain millions of wallets across dozens of L1/L2s while maintaining second-level freshness.

Below is a granular, subsystem-by-subsystem description of how these principles manifest in production.

A. On-Chain Contract Suite (TaxChainCore)

Contract
Network
Purpose
Key Patterns

BeaconRoot

Ethereum mainnet

Stores monthly Merkle roots for every user snapshot; anchors L2 / side-chain proofs.

EIP-1967 upgradeable beacon + Sparse Merkle Treecommitments

pNFTMinter

Same as user’s primary chain (defaults to mainnet)

Mints & burns Permission NFTs; encodes access scopes as base64 in ERC-721 tokenURI.

ERC-721 + EIP-5192 (soul-bound) + EIP-712 meta-tx

RulebookRegistry

Ethereum & mirrored on each supported L2

Stores IPFS CIDs + SHA-256 hashes for every jurisdictional rulepack version.

EIP-2535 Diamond proxy to append facets without redeploy

FeeVault

Arbitrum One

Collects protocol fees, distributes to stakers and plugin authors.

EIP-4626 tokenised vault + streaming Sablier contracts

GovernanceRouter

Ethereum, Arbitrum, Optimism (via LayerZero)

Cross-chain DAO proposal execution + timelock.

Diamond + LayerZero OFT cross-chain messaging

Gas Optimisation: All contracts are written in Yul+ or verified Huff where appropriate. Critical paths use custom calldata decoding to shave ~8 % gas. Beacon writes occur once per month per user, amortising anchor cost to << $0.01 on L2.

B. Data-Ingestion Mesh

  1. Shard Listeners Rust-based, no-std binaries compile to MUSL and run inside containerd pods across three geographic regions (eu-central-1, us-east-1, ap-southeast-1).

    • EVM Chains: Uses Erigon gRPC TraceBlocks with --max-tx-fee=0 to catch ↄ-bundle reverts.

    • Solana: Streams via Firehose for 500 ms latency.

    • IBC / Cosmos: Polls ABCI events; automatically detects chain-id changes on upgrades.

  2. TxEvent Canonicaliser Implements a lossless IL (Intermediate Language) with 34 opcodes covering all L1 semantics. Each canonicalised event is hashed:

    h=Keccak256(IL ∥ blockHeight ∥ chainID)

    and streamed to Kafka topics partitioned by h[0..7] for even shard distribution.

  3. Reorg Guardian Maintains a rolling Bloom filter of the last 128 block hashes. If a fork deeper than 2 blocks is detected, Guardian broadcasts a REORG_ALERT topic; downstream processors rewind via the write-ahead log and replay.

C. Classification & Jurisdiction Engines

These run inside Cartesi roll-ups (deterministic RISC-V VMs) for on-chain verifiability without L1 gas costs.

  • Input: batch of canonical IL traces + Rulebook version hash + Plugin manifest Merkle root.

  • Execution:

    1. Heuristic pass: Vectorised finite-state automata implemented in Rust + SIMD (AVX-512) classify ~70 % of events in O(-) linear time.

    2. ML pass: Compiled XGBoost model (binary) loaded into guest memory; predictions generated with deterministic float rounding to avoid non-det reproducibility issues.

    3. Conflict resolver: Edge-weighted DAG chooses canonical tag.

  • Output: cATU objects, each with (tag, confidence, jurisdiction_hint).

Verifiability: The Cartesi output root is posted to Arbitrum as calldata; a watcher network can challenge with fraud proofs. This guarantees that even off-chain ML execution is economically bonded.

D. Tax Graph & Snapshot Storage

  1. Schema – Content Addressed Merkle DAG where every node’s cid embeds blake3(parent || payload) for collision resistance. Stored in IPFS-Cluster with 12 replicas.

  2. Encryption – Each payload encrypted under XChaCha20-Poly1305 with a symmetric key K_user_month. K_user_month is derived via:

    K=HKDF_SHA256(sig(Hsnapshot),  userPubKey∥month_salt)

    where sig is user’s EIP-191 signature of the snapshot hash.

  3. Anchoring – Monthly, a Merkle root of encrypted CIDs is published to BeaconRoot (contract §A) with:

    function commit(bytes32 merkleRoot, bytes32 userKey, uint32 month) external;

    ensuring permanent timestamping.

E. Monthly Report Compiler

Deployed as WASM workers (wasmtime) orchestrated by Nomad:

  • Phase 1 : Loading Memory-maps snapshot Parquet columns (transaction id, fiat_value, tag, rule-id) using zero-copy.

  • Phase 2 : Jurisdiction Folding For each jurisdiction, a data-flow graph (petgraph) runs holding-period tests, cost-basis evaluation, and gain/loss folding with branchless SIMD kernels.

  • Phase 3 : FX Correction Pulls USD/EUR/CHF rates from Pyth price attestations; cross-checks with ECB SSM for EUR consistency; uses max(stdev, 1 %) to pad in high-volatility days.

  • Phase 4 : Render

    • PDF: Apache FOP inside WASM with pre-rendered SVG charts; fonts subsetted via Harfbuzz.

    • XBRL: Validated via Arelle rulesets compiled to WASM.

Compilation artefacts hashed with BLAKE3 and stored (encrypted) in snapshot.

F. Permission NFT Gateway

Implemented as a stateless gRPC façade:

  1. Handshake Advisor wallet signs EIP-712 message referencing pNFT tokenId + request scope.

  2. Key Derivation Server verifies pNFT in pNFTMinter.ownerOf(tokenId) and derives decryption key:

    Kdecrypt=HKDF_SHA256(userPubKey∥advisorPubKey∥scopeHash)

  3. Data Filtering An eBPF filter off the side-car FS ensures only CIDs matching scope hash are decrypted.

  4. Streaming Files streamed over HTTP 2 with per-chunk AES-GCM; rate-limit R=500 KiB s⁻¹ to throttle DDoS vectors.

All gateway calls append signed access logs to an Auditable Append-Only Log (AAOL) built on Trillian.

G. Governance & Upgrade Mechanics

  1. Dual-Chain DAO

    • Arbitrum for cheap voting snapshots (GovernorBravo fork).

    • Ethereum for canonical state; LayerZero relays outcome.

  2. Proposal Classes

    • RulebookUpdate – adds new rule pack; timelock 2 days.

    • CoreCodeUpgrade – upgrades diamond facet; timelock 5 days + guardian veto.

    • FeeChange – updates FeeVault parameters; timelock 3 days.

  3. Guardian Council Five-of-nine multisig, revocable by DAO, can pause beacon commits or revert upgrades during 7-day grace.

H. Plugin Marketplace

Every third-party protocol classifier or exchange adapter is packaged as a WASM module signed by the author and registered in PluginRegistry, a facet of RulebookRegistry.

  • Registration Flow

    1. Author posts WASM binary → IPFS, submits SHA-256.

    2. Unit tests (Fuzz + KnownTx vectors) run inside CI; must hit 99 % precision.

    3. DAO vote stakes 200 000 TCHAIN tokens to activate.

  • Runtime WASM plugins loaded in wasmtime with compute cap 50 ms & mem cap 1 MiB; gas-metering compiled in via wasm-metering.

  • Revenue 20 % of fee revenue from ATUs classified by a plugin streams to author’s vault address via Sablier.

I. Interoperability & L2 Strategy

Layer
Technique
Details

L1 ↔ L2 Anchors

Optimistic Rollupbridges

Root ↔ Mirror of BeaconRoot; 1-hr challenge window

Cross-Chain Messaging

LayerZero OFT + ULN

All governance and fee-stream transfers

Bridged pNFTs

ERC-6551-like Account NFTs

Mirror contract on destination chain; maintains non-transferability by disabling safeTransferFrom

J. Security Posture

  • Audits – ChainSecurity, Trail of Bits, OpenZeppelin; re-audit every major release.

  • Bug-Bounty – Tiered up to $500 000 via Immunefi.

  • Formal Verification – Yul / Huff contracts model-checked in Certora.

  • Runtime Security – Run-time Application Self-Protection (RASP) agent monitors WASM runtime; kills pods on mem-overrun.

  • Key Compromise Recovery – Users may appoint Shamir guardians; two-of-three shares recreate decryption key if wallet lost.

K. Performance Benchmarks (2025-05-01)

KPI
Achieved
Notes

Ingestion latency

< 4 s from block finality to Tax Graph commit

Solana worst-case 5.2 s

Classification throughput

2.9 M cATU s⁻¹ per Cartesi roll-up

6 roll-ups = >1 B cATU day

Monthly report compile

≈ 11 ms / 1 000 ATU

user with 75 k tx compiles in 0.8 s

Gateway decrypt speed

> 150 MB s⁻¹ on 1 Gbps link

AES-NI accelerated

Anchor cost

$0.0024 per user (Arbitrum, 30 gwei equiv.)

amortised via batch

L. Roadmap Milestones

  1. Q3 2025 – zk-Proof of Compliance

    • Groth16 circuits proving “Tax paid ≥ X” without revealing ledger.

  2. Q4 2025 – Intent-Aware Module

    • ERC-7521 integration; classify off-chain intents before execution.

  3. Q1 2026 – Post-Quantum Hash Migration

    • Transition beacon commits to SPHINCS+ once NIST finalises curves.

  4. Q2 2026 – Data-Sovereign Residency Engine

    • Real-time jurisdiction switching based on tokenised e-SIM proofs.

In sum, TaxChain’s protocol design fuses high-performance off-chain compute with immutable on-chain guarantees, enabling a deterministic, transparent, and massively scalable tax-compliance layer for the entire crypto ecosystem. Every byte—from raw block data to the final PDF—is provably correct, cryptographically anchored, and upgradeable without sacrificing historical integrity, ensuring the platform can evolve alongside both Web3 innovation and ever-changing national tax laws.

PreviousNFT-Based Advisor AccessNextData Security & Privacy

Last updated