A mechanism design document is the engineering specification for a token economy: every mechanism named, every parameter given a value and a permitted range, every invariant stated, every privileged action listed, and every failure mode written down with what the system does when it occurs. It is the artifact an auditor, a smart contract engineer and a regulator's counsel can all read without asking what was meant. A whitepaper explains why the design exists. The MDD says exactly what it does.
If two engineers on the same team give different answers about what happens when a parameter hits its bound, there is no mechanism design document, whatever the file is called. The test is not whether a document exists. It is whether the document settles disagreements.
Scroll to see the full diagram
What separates it from a whitepaper
The two documents have different readers and different jobs. A whitepaper is written to persuade: it carries the thesis, the market, the reason the token exists. A mechanism design document is written to constrain: it is read by the person implementing the contracts and by the person auditing them, and its value is that it removes ambiguity rather than generating interest.
The consequence is that they cannot be merged without one of them failing. Parameter tables, bound conditions and failure handling make a poor investor narrative. A narrative makes an unusable build spec. Serious projects publish both and keep them in sync, and treat a divergence between them as a defect rather than an editorial matter.
Treating token design as a technical specification
The framing has standards-body support. NIST's overview of blockchain token design and management treats token design as a technical specification problem, covering the token lifecycle and the properties that have to be specified rather than described.1 That is the register an MDD is written in: a specification, with the same expectations of completeness a protocol spec carries.
Practitioner framing lands in the same place from the other direction. a16z crypto's treatment of blockchain mechanism design describes the work as reverse-engineering a game so that desired outcomes become equilibrium outcomes.2 A game defined only in prose has no defined equilibrium, which is why the parameter values and their bounds belong in the document rather than in someone's spreadsheet.
What a complete one contains
Six things, and each of them fails a build if it is missing. The stakeholder set and what each class can do. Every mechanism, stated as inputs, outputs and preconditions. Every parameter with its launch value, its permitted range and who may change it. The invariants that have to hold across all states, such as supply identities and collateral floors. Every privileged action, which pairs directly with the admin capability matrix. And the failure modes, each with the system's defined response.
An academic token-economy design method arrives at a similar order from first principles, sequencing the work as identifying the stakeholders, identifying the functions of the token economy, defining the desirable behaviours, selecting incentive-mechanism types, then specifying the mechanisms.3 Note that specifying comes last. Most drafts we see start there, which is why they read as a list of features rather than a design.
What happens when there is not one
Across the 100+ projects we have advised, the absence shows up in the same three places. The audit takes longer and costs more, because the auditor has to infer intent before they can test against it. The contracts encode a parameter nobody can explain the derivation of. And a governance proposal to change something turns into an argument about what the original design intended, with no document able to settle it.
The document also has a commercial function. A serious counterparty reading a data room can tell within minutes whether a project has specified its economy or narrated it, and that judgment travels to the diligence question that matters: whether there is a business underneath the token or a mechanism standing in for one.
Common questions
What is the difference between a whitepaper and a mechanism design document?
A whitepaper is written to persuade and carries the thesis, the market and the reason the token exists. A mechanism design document is written to constrain and carries parameters, ranges, invariants, privileged actions and failure responses. Their readers differ: one is read by investors and users, the other by the engineers implementing the contracts and the auditors testing them. Most projects need both, kept in sync.
What should a mechanism design document include?
The stakeholder set and what each class can do, every mechanism stated as inputs and outputs and preconditions, every parameter with a launch value and permitted range and change authority, the invariants that must hold in all states, every privileged action, and every failure mode with the system's defined response. An academic design method sequences the work from stakeholders through desirable behaviours to mechanism specification.3
Do we need one before a smart contract audit?
It makes the audit cheaper and more useful. Without a specification an auditor tests the code against inferred intent, which finds implementation bugs but not design errors, because there is no stated behaviour to compare against. With one, a mismatch between specified and actual behaviour is a finding. Standards-body treatments of token design put it in specification terms for the same reason.1
See Tokenomics Design Services for how this applies in practice.
Sources
- NISTIR 8301: Blockchain Networks, Token Design and Management Overview
U.S. National Institute of Standards and Technology (Lesavre, Varin, Yaga), 2021
Federal standards-body treatment of token design and lifecycle management as a technical specification problem rather than a narrative one. - 8 Reasons Why Blockchain Mechanism Design Is Hard
a16z crypto, 2026
Frames mechanism design as reverse-engineering a game so that desired outcomes become equilibrium outcomes. Read 3 August 2026. - Designing a Token Economy: Incentives, Governance, and Tokenomics
arXiv preprint, 2026
Five-step token-economy design method: identify stakeholders, identify functions, define desirable behaviours, select incentive-mechanism types, specify incentive mechanisms. Read 3 August 2026.
Last reviewed 2026-08
More in Mechanism Design Structures
Know the terms but not sure how they apply to your project? That is what an engagement is for. We design, document, and stress-test the whole token economy inside the Tokenomics Data Room.
100+ projects advised. Complete tokenomics in 4 to 6 weeks.