PreciseBank

​

Overview

• 18 decimal precision for EVM (10^18 sub-atomic units)
• Backward compatibility with 6 decimal Cosmos operations
• Transparent conversion between precision levels
• Fractional balance tracking for sub-test amounts

​

State

​

Balance Representation

atest_balance = test_balance × 10^12 + fractional_balance

• test_balance: Stored in x/bank (6 decimals)
• fractional_balance: Stored in x/precisebank (0 to 10^12-1)
• atest_balance: Full 18-decimal precision

​

Keeper Interface

type Keeper interface {
    // Query methods
    GetBalance(ctx, addr, denom) sdk.Coin
    SpendableCoins(ctx, addr) sdk.Coins
    
    // Transfer methods
    SendCoins(ctx, from, to, amt) error
    SendCoinsFromModuleToAccount(ctx, module, to, amt) error
    SendCoinsFromAccountToModule(ctx, from, module, amt) error
    
    // Mint/Burn methods
    MintCoins(ctx, module, amt) error
    BurnCoins(ctx, module, amt) error
}

​

Extended Coin Support

• Converts between test and atest transparently
• Maintains fractional balances for sub-test amounts
• Ensures consistency between x/bank and x/precisebank

​

Operations

​

Transfer

// SendCoins automatically handles precision
keeper.SendCoins(ctx, from, to, sdk.NewCoins(
    sdk.NewCoin("atest", sdk.NewInt(1500000000000)), // 0.0015 test
))

1. Subtract from sender (update b(sender) and f(sender))
2. Add to receiver (update b(receiver) and f(receiver))
3. Update reserve based on carry/borrow
4. Remainder unchanged (mathematical guarantee)

​

Mint

// MintCoins with extended precision
keeper.MintCoins(ctx, moduleName, sdk.NewCoins(
    sdk.NewCoin("atest", sdk.NewInt(1000000000000000000)), // 1 test
))

1. Add to account (update b(account) and f(account))
2. Decrease remainder (tokens enter circulation)
3. Update reserve for consistency

​

Burn

// BurnCoins with extended precision
keeper.BurnCoins(ctx, moduleName, sdk.NewCoins(
    sdk.NewCoin("atest", sdk.NewInt(500000000000)),  // 0.0005 test
))

1. Subtract from account (update b(account) and f(account))
2. Increase remainder (tokens leave circulation)
3. Update reserve for consistency

​

Events

​

Transfer Events

​

Mint/Burn Events

​

Queries

​

gRPC

service Query {
    // Get total of all fractional balances
    rpc TotalFractionalBalances(QueryTotalFractionalBalancesRequest)
        returns (QueryTotalFractionalBalancesResponse);
    
    // Get current remainder amount
    rpc Remainder(QueryRemainderRequest)
        returns (QueryRemainderResponse);
    
    // Get fractional balance for an account
    rpc FractionalBalance(QueryFractionalBalanceRequest)
        returns (QueryFractionalBalanceResponse);
}

​

CLI

# Query total fractional balances
evmd query precisebank total-fractional-balances

# Example output:
# total: "2000000000000atest"

​

Integration

​

For EVM Module

app.EvmKeeper = evmkeeper.NewKeeper(
    app.PrecisebankKeeper, // Instead of app.BankKeeper
    // ... other parameters
)

​

For Other Modules

// Automatically handles atest denomination
balance := keeper.GetBalance(ctx, addr, "atest")

// Transfer with 18 decimal precision
err := keeper.SendCoins(ctx, from, to, 
    sdk.NewCoins(sdk.NewCoin("atest", amount)))

​

Reserve Account

Reserve_test × 10^12 = Σ(all fractional balances) + remainder

​

Monitoring Reserve

# Check reserve account balance
evmd query bank balances cosmos1m3h30wlvsf8llruxtpukdvsy0km2kum8g38c8q

# Verify invariant
evmd query precisebank total-fractional-balances
evmd query precisebank remainder

​

Invariants

​

Best Practices

​

Chain Integration

1. Reserve Monitoring
   • Track reserve balance for validation
   • Set up alerts for invariant violations
   • Regular audits of fractional sums
2. Migration Path
   Copy

   Ask AI

   // Deploy in passive mode
   app.PrecisebankKeeper = precisebankkeeper.NewKeeper(
       app.BankKeeper,
       // Fractional balances start at zero
   )
   

3. Testing
   Copy

   Ask AI

   // Verify fractional operations
   suite.Require().Equal(
       expectedFractional,
       keeper.GetFractionalBalance(ctx, addr),
   )
   

​

dApp Development

1. Balance Queries
   Copy

   Ask AI

   // Query in atest (18 decimals)
   const balance = await queryClient.precisebank.fractionalBalance({
       address: "cosmos1..."
   });
   

2. Precision Handling
   Copy

   Ask AI

   // Convert between precisions
   const testAmount = atestAmount / BigInt(10**12);
   const atestAmount = testAmount * BigInt(10**12);
   

​

Security Considerations

​

Overflow Protection

• All arithmetic uses checked math
• Fractional values bounded to [0, 10^12)
• Integer overflow impossible by design

​

Atomicity

• Balance updates are atomic
• Reserve adjustments in same transaction
• No intermediate states visible

​

Precision Guarantees

• No precision loss during operations
• All fractional amounts preserved
• Rounding only at display layer

​

Performance

​

Storage Impact

• Additional O(n) storage for accounts with fractional balances
• Most accounts have zero fractional balance (no storage)
• Reserve account: single additional balance

​

Computation

• Constant time operations for all transfers
• Single addition/multiplication for balance queries
• ~10% gas overhead for fractional updates

​

Optimization

• Lazy initialization (fractional balances start at zero)
• Sparse storage (only non-zero fractions stored)
• Batch operations maintain efficiency

​

Troubleshooting

​

Common Issues

​

Validation Commands

# Verify module invariants
evmd query precisebank total-fractional-balances
evmd query precisebank remainder

# Check specific account
evmd query bank balances cosmos1... --denom test
evmd query precisebank fractional-balance cosmos1...

​

References

​

Source Code

• PreciseBank Module - Implementation
• Keeper - Core logic
• Proto Definitions - API specs

​

Related Documentation

• Precision Handling - Mathematical foundation
• VM Module - EVM integration
• Bank Module - Underlying module