Taxr Smart Contract Architecture

Architecture Overview

The Taxr smart contract architecture follows a modular design pattern with a central orchestration contract and specialized manager modules:

                                                      ┌──────────────────┐
                                                      │   External Apps  │
                                                      └────────┬─────────┘
                                                               │
                                 ┌─────────────────────────────┼─────────────────────────────┐
                                 │                             │                             │
                         ┌───────▼───────┐             ┌───────▼───────┐             ┌───────▼───────┐
                         │  Web3 Client   │             │  Payment Router │             │  Other Services │
                         └───────┬───────┘             └───────┬───────┘             └───────┬───────┘
                                 │                             │                             │
                                 └─────────────────────────────┼─────────────────────────────┘
                                                               │
                                                      ┌────────▼─────────┐
                                                      │                  │
                                                      │   TaxrMastr      │
                                                      │   (Core)         │
                                                      │                  │
                                                      └───┬───────┬──────┘
                                                          │       │
                    ┌──────────────────────┬──────────────┘       └───────────┬─────────────────────────┐
                    │                      │                                   │                         │
            ┌───────▼─────────┐    ┌───────▼─────────┐                 ┌──────▼──────────┐      ┌───────▼─────────┐
            │                 │    │                 │                 │                 │      │                 │
            │ JurisdictionMgr │    │   ClaimManager  │                 │ CommissionMgr   │      │  SheriffToken   │
            │                 │    │                 │                 │                 │      │                 │
            └─────────────────┘    └─────────────────┘                 └─────────────────┘      └─────────────────┘
                     │                     │                                   │                         │
                     │                     │                                   │                         │
            ┌────────▼─────────┐  ┌────────▼─────────┐                ┌────────▼─────────┐     ┌────────▼─────────┐
            │ Jurisdiction     │  │ TaxrBill &       │                │ Commission        │     │ ERC721 Sheriff   │
            │ Token (ERC1155)  │  │ Receipt NFTs     │                │ Calculations      │     │ Badges           │
            └──────────────────┘  └──────────────────┘                └──────────────────┘     └──────────────────┘

Core Contracts

TaxrMastr (Proxy Implementation)

The central orchestration contract that coordinates all system functionality, now implemented as a proxy pattern:

Role: System orchestration and state management
Location: /taxr-persistence/contracts/proxy/TaxrMastrProxy.sol (Proxy)
Location: /taxr-persistence/contracts/proxy/TaxrMastrConcrete.sol (Implementation)
Key Functionalities:
- Module coordination and integration
- System-wide configuration
- Access control management
- Event emission and logging
- Proxy-based upgradeability
Design Pattern: ERC1967 Proxy with layered implementation contracts

TaxrMastrStorage

The storage layout contract for the proxy implementation:

Role: Define storage variables and layout
Location: /taxr-persistence/contracts/proxy/TaxrMastrStorage.sol
Key Functionalities:
- Storage layout definition
- State variable declarations
- Type-safe mappings and arrays
- Storage gap for upgrade safety
Pattern: Diamond Storage pattern for upgrade-safe state management

TaxrMastrBase

The foundation contract that TaxrMastr inherits from:

Role: Common functionality and base infrastructure
Location: /taxr-persistence/contracts/base/TaxrMastrBase.sol
Key Functionalities:
- Basic storage structures
- Common utility functions
- Error definitions and handling

SheriffToken

ERC-721 implementation for Sheriff identity badges:

Role: Represent tax authority identities
Location: /taxr-persistence/contracts/SheriffToken.sol
Key Functionalities:
- Minting sheriff badges
- Authority verification
- Metadata management
- Token URI handling
Standard: ERC-721 with role-based access control

TaxrToken

ERC-20 implementation with dual-layer design and burn-to-govern mechanism:

Role: Utility token for tax payments and governance
Location: /taxr-persistence/contracts/TaxrToken.sol
Key Functionalities:
- Utility token minting and burning
- Market token distribution
- USD value calculation
- Treasury management
- Faucet controls with permanent kill switch
- Burn tracking and reputation system
- burnFromVault for ETH-based claims
- Burn-to-govern token distribution
Design:
- Dual-layer with separate tracking for utility and market tokens
- Single-token governance system based on burn reputation
- Complete burn lifecycle management
Token Economy:
- Tokens burned for claim settlement
- Governance tokens claimed based on burn history
- Faucet control for gradual transition to market-only token

PaymentRouter

Multi-currency payment processor:

Role: Handle payments in ETH and ERC-20 tokens
Location: /taxr-persistence/contracts/PaymentRouter.sol
Key Functionalities:
- ETH and token payment processing
- Price feed integration
- Token conversion to TAXR
- Treasury operations
Integration: Works with Chainlink price feeds and other price sources

Manager Modules

JurisdictionManager

Manages tax jurisdictions as ERC-1155 tokens:

Location: /taxr-persistence/contracts/modules/JurisdictionManager.sol
Key Functionalities:
- Jurisdiction minting and management
- Geographic boundary integration
- Jurisdiction metadata handling
- Jurisdiction assignment to sheriffs
Token Standard: ERC-1155 for semi-fungible jurisdiction tokens

ClaimManager

Handles tax bill claims and receipts:

Location: /taxr-persistence/contracts/modules/ClaimManager.sol
Key Functionalities:
- Tax bill creation and management
- Claim processing and validation
- Receipt generation
- Claim state transitions
Bill Types: Supports multiple tax bill types through inheritance

CommissionManager

Manages commission structures and calculations:

Location: /taxr-persistence/contracts/modules/CommissionManager.sol
Key Functionalities:
- Commission rate configuration
- Fee calculation and distribution
- Sheriff reward management
- Platform fee handling
Integration: Works with ClaimManager for payment processing

Tax Bill Contracts

TaxrBill Base

Base contract for all tax bill types:

Location: /taxr-persistence/contracts/TaxrBills/TaxrBill.sol
Key Functionalities:
- Common bill properties and methods
- Bill ID generation
- Status management
Design: Abstract base contract for specialized bill types

PropertyTaxrBill

Specialized implementation for property tax bills:

Location: /taxr-persistence/contracts/TaxrBills/PropertyTaxrBill.sol
Key Functionalities:
- Property-specific data fields
- Assessment value handling
- Delinquency calculation
Integration: Used by ClaimManager for property tax claims

UpstartBill

Implementation for other types of government fees:

Location: /taxr-persistence/contracts/TaxrBills/UpstartBill.sol
Key Functionalities:
- General-purpose fee handling
- Flexible configuration
- Multiple fee type support
Use Case: Handles non-property taxes and government fees

Type Libraries

Specialized libraries for type-safe identifier handling:

Library	Purpose	Location
BillID	Unique tax bill identifiers	`/taxr-persistence/contracts/libraries/BillID.sol`
ClaimID	Tax claim identifiers	`/taxr-persistence/contracts/libraries/ClaimID.sol`
JurisdictionID	Tax jurisdiction identifiers	`/taxr-persistence/contracts/libraries/JurisdictionID.sol`
SheriffTokenID	Sheriff badge identifiers	`/taxr-persistence/contracts/libraries/SheriffTokenID.sol`
DomainID	System domain identifiers	`/taxr-persistence/contracts/libraries/DomainID.sol`
TaxrType	Type definitions and enums	`/taxr-persistence/contracts/libraries/TaxrType.sol`
TypeComparisons	Type-safe comparison utilities	`/taxr-persistence/contracts/libraries/TypeComparisons.sol`

Interface Contracts

Interface definitions for contract interactions:

Interface	Purpose	Location
ITaxrMastr	Core contract interface	`/taxr-persistence/contracts/interfaces/ITaxrMastr.sol`
ISheriffToken	Sheriff token interface	`/taxr-persistence/contracts/interfaces/ISheriffToken.sol`
ITaxrMastrToken	TAXR token interface	`/taxr-persistence/contracts/interfaces/ITaxrMastrToken.sol`
IPaymentRouter	Payment router interface	`/taxr-persistence/contracts/interfaces/IPaymentRouter.sol`
IPriceSource	Price feed interface	`/taxr-persistence/contracts/interfaces/IPriceSource.sol`
ITaxMasterEventEmitter	Event emission interface	`/taxr-persistence/contracts/interfaces/ITaxMasterEventEmitter.sol`
ITaxMasterErrorEmitter	Error handling interface	`/taxr-persistence/contracts/interfaces/ITaxMasterErrorEmitter.sol`

Proxy Architecture

The TaxrMastr contract implements an ERC1967 proxy pattern to overcome Ethereum's 24KB contract size limitation while providing upgradeability:

                    ┌───────────────────┐
                    │                   │
                    │   TaxrMastrProxy  │◄───── User Interactions
                    │   (ERC1967)       │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ delegatecall
                              ▼
                    ┌───────────────────┐
                    │                   │
                    │ TaxrMastrConcrete │
                    │ (Implementation)  │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ inheritance
                              ▼
                    ┌───────────────────┐
                    │                   │
                    │   TaxrMastrFull   │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ inheritance
                              ▼
                    ┌───────────────────┐
                    │                   │
                    │ TaxrMastrModules  │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ inheritance
                              ▼
                    ┌───────────────────┐
                    │                   │
                    │   TaxrMastrImpl   │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ inheritance
                              ▼
                    ┌───────────────────┐
                    │                   │
                    │ TaxrMastrStorage  │
                    │                   │
                    └───────────────────┘

Proxy Components

TaxrMastrProxy: ERC1967 proxy that delegates all calls to the implementation contract
TaxrMastrStorage: Base contract defining all storage variables (prevents layout corruption during upgrades)
TaxrMastrImpl: Core implementation with initialization logic and essential functionality
TaxrMastrModules: Extended business logic for specific system features
TaxrMastrFull: Combined implementation with bidirectional flows and comprehensive features
TaxrMastrConcrete: Final implementation contract that provides concrete functionality

Key Proxy Features

Initialization Pattern: Uses initialize() function instead of constructors for proxy compatibility
Storage Separation: Clear separation of storage from logic to prevent layout corruption
Delegated Execution: All function calls to the proxy are delegated to the implementation
Upgradeability: Implementation contract can be replaced while preserving storage state
Type Safety: Maintains type safety across the entire proxy implementation chain

Business Flow Support

Sheriff-First Flow: Sheriff creates bill, taxpayer claims it
Taxpayer-First Flow: Taxpayer submits claim, sheriff creates bill from it
Combined Flow: Flexible system supporting both approaches through mintBillFromClaim

Commission-Based Authorization

Three-Level Model: Sheriff → Jurisdiction → Domain authorization
Temporal Control: Commissions with start and end timestamps
Domain Specificity: Fine-grained control over which domains a sheriff can operate in

Design Patterns

Modular Architecture

The Taxr smart contract system uses a modular architecture with the following benefits:

Separation of Concerns: Each module handles a specific aspect of functionality
Upgradability: Modules can be upgraded independently
Gas Efficiency: Smaller, focused contracts reduce deployment and execution costs
Development Scalability: Multiple developers can work on different modules

Type-Safe Identifiers

Custom type wrappers with the TypeComparisons library provide:

Type Safety: Prevents mixing different ID types
Compile-time Checking: Catches errors early in development
Self-documenting Code: Clear parameter types improve code readability
Reduced Bugs: Minimizes incorrect ID usage

Interface Segregation

Interfaces are segregated by functionality:

Event Interfaces: Separate from method interfaces
Error Interfaces: Group related errors
Implementation Interfaces: Define required functionality

Role-Based Access Control

The system implements comprehensive role-based access control:

Admin Roles: System configuration and management
Sheriff Roles: Tax authority operations
Operator Roles: Day-to-day system operations
Treasury Roles: Financial management

Integration Points

Frontend Integration

The smart contracts integrate with the frontend through:

TypeChain: Generated TypeScript type definitions
ABI Exports: Automatically exported ABIs for frontend use
Events: Real-time updates through contract events
Proxy Transparency: Frontend interacts with proxy without knowing implementation details

External Services

The system integrates with external services through:

Price Feeds: Chainlink oracles for token pricing
WASM Modules: Rust-based verification components
Payment Systems: Multi-currency payment processing

Proxy Upgrade System

The proxy upgrade mechanism provides critical integration functionality:

Upgrade Transparency: Users continue to interact with the same proxy address after upgrades
Implementation Changes: Logic can be updated without migrating state or changing user interfaces
Backward Compatibility: Upgrades maintain compatibility with existing data structures
Access Control: Only authorized addresses can perform upgrades (typically contract owner)
Upgrade Events: Implementation changes emit events for transparency and monitoring

Testing Framework

The smart contracts are thoroughly tested using:

Foundry Tests: Solidity-native testing with forge-std
Hardhat Tests: JavaScript-based tests
Mock Contracts: Simulation of external dependencies
Integration Tests: End-to-end testing of contract interactions

Test files can be found in /taxr-persistence/test/ directory.

Development & Deployment

Development Tools

Foundry: Primary development and testing framework
Hardhat: TypeScript integration and deployment
Solidity 0.8.28: Smart contract language

Deployment Scripts

The contracts can be deployed using:

Forge Scripts: /taxr-persistence/scripts/DeployTaxr.s.sol
Hardhat Ignition: /taxr-persistence/ignition/modules/DeployTaxr.ts

Development Commands

Build: forge build or npm run build:blockchain
Test: forge test or npm test
Deploy (Local): npm run deploy:local:anvil