type-driven-design

Type-Driven Solidity Design

Type-driven design replaces object inheritance with struct composition and free functions. Instead of deep inheritance trees where storage layouts are hidden and method overriding is opaque, each data concern is a standalone struct with free functions bound via using ... for ... global. Contracts compose these types and serve only as the external interface.

Reference implementation: jtriley2p/type-driven-tokens

Why This Matters

Inheritance-based Solidity creates problems that compound as protocols grow:

• Hidden interfaces — parent contracts add external/public functions implicitly
• Storage layout opacity — storage slots are scattered across an inheritance tree
• Method override fragility — virtual/override chains break silently on refactor
• Testing requires mocks — abstract contracts can't be tested without mock inheritors
• Inheritance hell — diamond inheritance, linearization surprises, C3 ambiguity

Type-driven design eliminates all of these. The entire external interface is explicit in one contract. Storage is visible as struct composition. Each component is independently testable without mocks.

Core Principles

1. Types Encapsulate Storage

Each struct wraps the minimum storage it needs. The internal field is private by convention (_inner).

struct Balances {
    mapping(address => uint256) _inner;
}

struct TotalSupply {
    uint256 _inner;
}

struct Allowances {
    mapping(address => mapping(address => uint256)) _inner;
}

struct Operators {
    mapping(address => mapping(address => bool)) _inner;
}

2. Free Functions Define Behavior

Behavior is defined as free functions (file-level, outside any contract) bound to the struct with using ... for ... global. Every mutating function takes Type storage self and returns Type storage for fluent chaining.

using { read, write, increase, decrease } for Balances global;

function read(Balances storage self, address account) view returns (uint256) {
    return self._inner[account];
}

function write(Balances storage self, address account, uint256 amount) returns (Balances storage) {
    self._inner[account] = amount;
    return self;
}

function increase(Balances storage self, address account, uint256 amount) returns (Balances storage) {
    self._inner[account] += amount;
    return self;
}

function decrease(Balances storage self, address account, uint256 amount) returns (Balances storage) {
    self._inner[account] -= amount;
    return self;
}