TAXR Token - Technical Documentation

Overview

TAXR is an ERC-20 compliant token that powers real-world claim settlement, treasury flow, and token-based compression through enforced burns. It implements a dual-layer system that separates market tokens from utility tokens while maintaining a single token standard.

Token Architecture

Dual-Layer System

The token implements a dual-layer design that distinguishes between different token uses:

Layer	Purpose	Lifecycle
Market Layer	Tradable TAXR from treasury, used for governance and market incentives	Permanent (float)
Utility Layer	Temporary TAXR for tax claim settlements	Minted per use, then burned

┌──────────────────────────────────────────────────────────┐
│                       TAXR Token                          │
├──────────────────────────┬───────────────────────────────┤
│        Market Layer      │         Utility Layer         │
├──────────────────────────┼───────────────────────────────┤
│ • Tradable               │ • Minted for specific use     │
│ • Governance rights      │ • Burned after settlement     │
│ • Staking rewards        │ • Fixed at $0.10/token        │
│ • LP incentives          │ • Tracked separately          │
└──────────────────────────┴───────────────────────────────┘
                │                        │
        ┌───────▼────────┐      ┌───────▼────────┐
        │  Market Flow   │      │  Utility Flow  │
        └───────┬────────┘      └───────┬────────┘
                │                        │
┌───────────────▼──────────┐   ┌────────▼───────────────┐
│ • Secondary market       │   │ 1. Taxpayer pays claim │
│ • DAO treasury           │   │ 2. Utility TAXR minted │
│ • Governance allocation  │   │ 3. Claim settled       │
│ • Protocol incentives    │   │ 4. TAXR burned         │
└──────────────────────────┘   └────────────────────────┘

Key Components

1. Burn Lifecycle Management

The token implements comprehensive burn tracking and management:

Utility Burns: Tracked via utilityBurned mapping and totalUtilityBurned counter
General Burns: Tracked via totalBurned mapping for all burn operations
Burn Event: _afterTokenTransfer() hook captures all burns automatically
Vault Burns: burnFromVault() function for ETH-based claims

2. Faucet Controls

The token includes faucet controls for gradual transition to market-only token:

Temporary Control: faucetOpen boolean to enable/disable public minting
Permanent Shutdown: killFaucet() permanently disables faucet
Admin Override: Admins can still mint despite faucet status

3. Governance Distribution System

The burn-to-govern mechanism rewards addresses that have burned tokens:

Qualification: Addresses must burn minimum threshold (configurable)
Distribution Ratio: Configurable ratio of burned tokens to governance tokens
Claiming: claimGovernanceShare() function for eligible addresses
Single Token Model: Governance tokens are regular TAXR from the governance reserve

TODO: Governance distribution policy needs finalization, including:

Epoch timing (monthly/quarterly claiming windows)
Progressive or flat reward structure
Caps on governance tokens per address
Time-weighted claiming formulas

4. Supply Management

The token manages its supply with careful allocation:

Allocation	Amount	Purpose
Tax Settlement	1,000,000,000 TAXR	Reserved for tax claims settlement
Treasury	1,000,000,000 TAXR	Protocol treasury for operations
Jurisdiction Onboarding	750,000,000 TAXR	Incentives for jurisdiction participation
Emissions & Staking	1,000,000,000 TAXR	Protocol rewards and staking incentives
Liquidity Seeding	500,000,000 TAXR	Market liquidity bootstrapping
Development Fund	500,000,000 TAXR	Development and growth initiatives
Governance Reserve	250,000,000 TAXR	Governance distribution to participants

Technical Implementation

Contract Structure

The TaxrToken contract is an ERC-20 implementation that inherits from multiple OpenZeppelin contracts:

contract TaxrToken is ERC20, ERC20Burnable, AccessControl, ERC2771Context {
    // Role definitions
    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant UTILITY_MINTER_ROLE = keccak256("UTILITY_MINTER_ROLE");
    bytes32 public constant TREASURY_ROLE = keccak256("TREASURY_ROLE");
    
    // Token constants, tracking, and storage
    // ...

    // Implementation of token functionality
    // ...
}

Role-Based Access Control

The token implements a comprehensive role system:

Role	Purpose	Key Functions
DEFAULT_ADMIN_ROLE	DAO governance / deployment owner	Grant/revoke other roles
ADMIN_ROLE	Reserve management / configuration	setReserveAddresses, initializeTokenSupply
MINTER_ROLE	Mint tradable TAXR	mint
UTILITY_MINTER_ROLE	Mint and burn utility-layer TAXR	mintUtility, burnUtility, transferUtility
TREASURY_ROLE	Treasury operations	burnFromVault

Key Functions

The contract implements the following key functions:

Token Supply Management

// Initialize the token supply by allocating to reserve addresses
function initializeTokenSupply() external onlyRole(ADMIN_ROLE);

// Mint tokens for the market layer
function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE);

Utility Layer Functions

// Mint tokens specifically for the utility layer (tax payment)
function mintUtility(address to, uint256 amount) external onlyRole(UTILITY_MINTER_ROLE);

// Burn tokens specifically for the utility layer (tax settlement)
function burnUtility(address from, uint256 amount) external onlyRole(UTILITY_MINTER_ROLE);

// Burn tokens from the treasury vault for ETH-based claims
function burnFromVault(uint256 amount) external onlyRole(TREASURY_ROLE);

Faucet Control Functions

// Open or close the public faucet
function setFaucetStatus(bool isOpen) external onlyRole(ADMIN_ROLE);

// Permanently close the faucet, cannot be reopened
function killFaucet() external onlyRole(ADMIN_ROLE);

Governance Distribution Functions

// Enable or disable governance share claiming
function setGovernanceSharesEnabled(bool enabled) external onlyRole(ADMIN_ROLE);

// Set governance share claim parameters
function setGovernanceParameters(uint256 ratio, uint256 minBurn) external onlyRole(ADMIN_ROLE);

// Claim governance tokens based on burn history
function claimGovernanceShare(address recipient) external returns (uint256);

Utility Functions

// Calculate the USD value of TAXR tokens (utility layer only)
function calculateUsdValue(uint256 amount) public pure returns (uint256);

// Calculate the TAXR tokens required for a given USD amount
function calculateTokensForUsd(uint256 usdAmount) public pure returns (uint256);

Burn-Based Economic Model

The TAXR token implements a burn-based model that enforces token compression and civic accountability:

           ┌─────────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
           │                 │     │             │     │             │     │             │
           │  Taxpayer pays  │────▶│  Mint TAXR  │────▶│  Settle    │────▶│  Burn TAXR  │
           │  claim (ETH)    │     │  utility    │     │  claim     │     │             │
           │                 │     │             │     │             │     │             │
           └─────────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
                 │                                                                 │
                 │                                                                 │
           ┌─────▼─────────┐                                                ┌──────▼──────┐
           │               │                                                │             │
           │   Protocol    │                                                │  Burn-based │
           │   retains ETH │                                                │  governance │
           │               │                                                │             │
           └───────────────┘                                                └─────────────┘

Key economic principles:

Value Transit: Taxpayers don't hold value, they transit value through the protocol
Token Compression: Burns reduce total supply over time
Burn Reputation: Burning activity creates governance eligibility
ETH Collateralization: Protocol retains ETH as treasury collateral

Note: The taxpayer's payment is essentially tokenized through the utility layer, used for settlement, then burned. This mechanism creates a one-way flow that compresses the token supply while maintaining value in the protocol treasury.

Meta-Transaction Support

The token implements ERC-2771 for gas-free transactions:

Trusted Forwarders: Configurable trusted forwarder addresses
Message Context: Properly overrides message context methods
Gas Sponsorship: Enables third-party gas payment

function _msgSender() internal view override(Context, ERC2771Context) returns (address) {
    return ERC2771Context._msgSender();
}

function _msgData() internal view override(Context, ERC2771Context) returns (bytes calldata) {
    return ERC2771Context._msgData();
}

Testing Strategy

The TaxrToken contract is thoroughly tested with the following test cases:

Utility Layer Tests: Tests for minting, burning, and tracking utility tokens
Market Layer Tests: Tests for market token distribution and treasury management
Faucet Control Tests: Tests for faucet open/close/kill functionality
Burn Tracking Tests: Tests for tracking burn operations across both layers
Treasury Burn Tests: Tests for treasury vault burn operations
Governance Share Tests: Tests for burn-based governance token distribution
Role-Based Access Tests: Tests for proper role restrictions

Test files:

/taxr-persistence/test/test_TaxrToken.t.sol: Basic token functionality tests
/taxr-persistence/test/test_TaxrToken_Functionality.t.sol: Integration tests with TaxrMastr
/taxr-persistence/test/test_TaxrToken_Burn_Lifecycle.t.sol: Burn lifecycle and governance tests

Integration Points

TaxrMastr Integration

The token integrates with the TaxrMastr contract for claim settlement:

TaxrMastr receives payment for claim
TaxrMastr calls mintUtility to create utility TAXR
Claim is processed and settled
TaxrMastr calls burnUtility to burn the tokens

PaymentRouter Integration

The token integrates with PaymentRouter for multi-currency support:

PaymentRouter accepts ETH or other tokens
Converts payment to equivalent TAXR value
For ETH payments, calls burnFromVault

Frontend Integration

The token integrates with the frontend through:

TypeChain-generated TypeScript types
Events for real-time updates
ABI exports for direct interaction

Future Considerations

Governance System Finalization:

The governance distribution system needs policy finalization to address the following aspects:

Epoch-based claiming vs. continuous claiming
Governance token caps to prevent excessive concentration
Progressive reward functions to incentivize certain behaviors
Time-weighted formulas to reward long-term participants
Governance token recovery mechanisms

Potential Enhancements

Dynamic Pricing: Integration with price feeds for market-based token value
Voting Mechanisms: Direct integration with governance systems
Staking Rewards: Additional incentives for token holders
Token Upgrades: Proxy-based upgradability for token contract

TAXR Token – Technical Documentation