Docs& integration

You are here because a token you are considering listing, pooling, lending against or paying with is built on this framework, and you need to know whether it will behave. There are two questions, and conflating them is the mistake these pages exist to prevent.

StatusInternal auditTests238 passingCoverage98.84%

Start here

The one call, what it returns, and how long the answer stays true.

01OverviewWhat this framework is, what it is not, and the single call that makes the rest of these pages optional.02The five-minute versionEstablish the tier, read the word, branch on the bits. Everything else in these pages is elaboration on those three steps.03What is fixed, what movesThe most useful distinction in these pages: which answers you may cache forever, and which ones you have to watch.

Verification

Whether to believe the declaration, established from the token's bytecode rather than from anything it says.

04Which tier is this token inThree tiers, one bytecode read to tell them apart, and a precise account of what each one is worth.05Verifying the codeOne EXTCODECOPY against forty-five bytes, why it beats a registry, and why the answer is safe to cache forever.06The shared runtimeOne deployed contract every canonical token executes, why it carries modules a given token never installs, and the size budget that closes the set.

Reference

The declaration surface in full: every flag, every identifier, and the pipeline they describe.

07Behaviour flagsNine bits, their values, what each one costs you, and the two combinations that cannot exist on chain.08Extensions and their dataWhat is installed, how each identifier is derived, and how to decode a module's live configuration.09The transfer pipelineFour phases in a fixed order, why the order is fixed in exactly one place, and what you can observe from outside.10Per-account stateOne call returns every per-account flag the installed modules maintain, and it is always safe to make.

Integrating

One page per behaviour, written from the perspective of the protocol that has to survive it.

11Fee on transferWhat the token guarantees, four integration patterns with their trade-offs, and the inversion everyone gets wrong by hand.12Transfer hookAn external call on the transfer path: what it can and cannot do, how much gas to hold, and why a failed transfer no longer means insufficient funds.13Pause and blocklistERC-1404 codes, the matrix of what each lever actually stops, and why a frozen counterparty is a liquidation signal.14Non-transferableTransfers always revert, there is no way to switch it off, and that is exactly what the declaration is for.15UpgradeableThe flag that qualifies every other one, and the single question to ask before relying on any of them.16Mintable and seizableThe two bits nothing reveals until they are used, who holds them, and the question that has to be answered before any other separation of keys means anything.

Building

Assembling a token from the modules, and deciding who may configure what.

17Assembling a tokenInherit the modules you want, initialise each one, seal the registry. The order you list them in does not matter, and that is the point.18AuthoritiesOne role per extension, dispatched through a single function, so modules know nothing about the access-control scheme the assembly chose.19Chain requirementsOne hard dependency, what it rules out, and why no chain support matrix is published here.

Clients

Off-chain reading, measured costs, and the list to run before you ship.

20TypeScript and viemThe same shape off-chain: resolve the tier from bytecode, read the word, and never let a revert become a zero.21What a transfer costsMeasured, not estimated. What the pipeline adds, what each behaviour adds, and why discovery adds nothing at all.22Integration checklistThe list to keep next to the pull request, in the order the questions actually have to be answered.