Key Takeaways
- What it is: The share of first-time addresses or attributed entities that return and perform qualifying activity later.
- How it is built: Users are grouped by first qualifying activity period, then measured for return activity over defined intervals.
- Core expression: Retention at period n = cohort members active in period n ÷ original cohort size, under a fixed entity and activity definition.
- Best use: Retention is often more informative than acquisition spikes because it tests whether activity persists after incentives or events.
- Main limitation: Wallet rotation understates retention; shared wallets overstate it; cross-chain migration looks like churn; bots can appear highly retained.
- Practical rule: Before trusting a retention figure, check how the metric handles wallet rotation, shared or custodial addresses, and cross-chain migration, since each can push the reported rate away from actual user behavior.
Who This Guide Is For
On-chain retention borrows a method from product analytics and applies it to a data source that does not support its central assumption. In a product, the user id is stable. On chain, the address is not, and it is not supposed to be.
Read this page if you want to run cohort retention on chain data and need to know how far the resulting curve can be trusted. The construction section covers the address-rotation problem in detail, because every honest on-chain retention number is a lower bound and the size of the understatement is chain-specific.
Educational content. Not individualized financial advice.
What Does On-Chain User Retention Measure?
On-chain retention measures how many addresses that were first active in one period were active again in a later period. It is a repeat-activity rate for addresses, expressed as a curve over elapsed time since first appearance.
What it does not measure is whether people came back, and the gap is systematic rather than random. A user who returns using a fresh address, which is normal wallet behavior on UTXO chains and privacy-conscious behavior everywhere, is scored as churned. Retention computed on addresses is therefore biased downward by construction, and the bias is larger on chains and wallets that rotate addresses more aggressively.
Plain-language definition
On-chain retention is the share of addresses from a starting cohort that show up again later. It is a floor on how many participants returned, not an estimate of it.
Technical definition
Define cohort C(t) as the set of addresses whose first observed activity falls in period t. Retention at lag n is |{a ∈ C(t) : a active in period t+n}| ÷ |C(t)|. The curve over increasing n is the retention curve. Variants differ on whether an address counts as retained if active in any period up to t+n (cumulative) or only in t+n itself (classic), and these produce very different-looking curves from identical data.
How Is On-Chain User Retention Constructed?
Building the curve requires three commitments that are frequently left unstated and that determine the result.
- First-appearance definition. An address is assigned to the cohort of its first observed activity. This requires a full historical scan, and it means the cohort assignment for any address is fixed forever by one event.
- Activity definition. Sending, receiving, or either. Receiving is passive, so a cohort measured on receiving activity can show retention driven entirely by other people sending to it, including spam.
- Retention definition. Classic returns activity in exactly period
t+n. Cumulative returns activity at any point throught+nand is monotonically higher. Publishing one and labeling it the other is a common and material error.
The address-rotation problem
Hierarchical deterministic wallets derive a new address for each receive, and most modern wallet software does this without the user being aware. A person who transacts weekly for a year may never reuse an address. Under address-based retention that person appears as fifty-two separate one-period cohorts, each with zero retention.
Entity clustering partially addresses this by grouping addresses that provably share ownership, most commonly through the common-input heuristic, where multiple inputs to one transaction are assumed to share a controller. It recovers some rotated addresses and misses others, and it fails entirely against wallets designed to defeat it. Clustered retention is higher than address retention and is still a lower bound.
Formula and Measurement Logic
Retention(t, n) = |C(t) ∩ A(t+n)| ÷ |C(t)|
whereC(t)is the cohort first active in periodtandA(t+n)is the set of addresses active in periodt+n.
The arithmetic is a set intersection over a set size. The measurement problem is that C(t) is a set of addresses rather than of participants, and the mapping between them is many-to-one in an unknown ratio that varies by cohort.
| Decision | Options | Effect on the curve |
|---|---|---|
| Retention type | Classic or cumulative | Cumulative is always higher; curves are not comparable |
| Activity side | Send, receive, or either | Receive-side retention can be driven by inbound spam |
| Period length | Day, week, month | Longer periods mechanically raise retention |
| Identity unit | Address or clustered entity | Clustering raises the curve and remains a lower bound |
| Contract addresses | Included or excluded | Contracts retain near-perfectly and distort the curve |
| Cohort period | Which starting month | Incentive-era cohorts behave nothing like organic ones |
How Should On-Chain User Retention Be Interpreted?
Read the shape, not the level. The level is a lower bound of unknown tightness. The shape, compared between cohorts measured identically, is where the information is.
- A steep initial drop followed by a flat tail is the normal shape. The flattening point is the more interesting feature than the drop, because it indicates the fraction of the cohort that became durable participants.
- A curve that never flattens indicates continuous attrition with no durable core, which is what single-use address creation produces.
- Cohort-over-cohort comparison is the strongest use. If the month-six retention of successive cohorts is rising, something changed for the better, and the address-rotation bias affects both cohorts similarly so it partly cancels.
Comparing an absolute retention level against a benchmark from product analytics is not meaningful. A software product measuring stable user ids and a chain measuring rotating addresses are not producing the same statistic, and on-chain numbers will look catastrophic by comparison for purely mechanical reasons.
Contract addresses, if included, retain almost perfectly because they are invoked continuously. On a contract-heavy chain their inclusion can dominate the curve and make retention look far better than participant behavior warrants.
Step-by-Step Workflow
- State whether the curve is classic or cumulative retention.
- State whether activity means sending, receiving, or either.
- Exclude contract addresses, or report the curve separately with and without them.
- Compute at entity level as well as address level; the gap estimates the rotation bias.
- Check whether the cohort period overlaps an airdrop or incentive campaign.
- Compare cohorts against each other rather than against an external benchmark.
- Report the level as a lower bound explicitly.
Worked Hypothetical Scenario
Two cohorts from the same chain, measured identically, six months after first activity.
| Cohort | Size | Month 1 | Month 3 | Month 6 |
|---|---|---|---|---|
| January (incentive campaign running) | 1,200,000 | 18% | 4% | 2% |
| July (no campaign) | 140,000 | 41% | 29% | 26% |
The January cohort is nearly nine times larger and retains 2 percent at six months, still falling. The July cohort is small and flattens near 26 percent between months three and six.
In absolute participant terms, January retained about 24,000 addresses at month six and July about 36,400, so the smaller cohort produced more durable participants than the campaign cohort despite being a ninth of the size. The campaign generated addresses, not participants.
The shape is the tell. January never flattens, which is the signature of single-use address creation. July flattens, which indicates a durable core. Note that both figures remain lower bounds: some share of each cohort returned under fresh addresses and is counted as churned in both.
What Can Make the Interpretation Wrong?
- Address rotation biases every curve downward. This is structural, not a data-quality issue, and the magnitude is unknown and chain-specific.
- Classic and cumulative curves get conflated. Cumulative retention is always higher, and the two are routinely compared as though interchangeable.
- Contract addresses inflate retention. They are invoked constantly and retain near-perfectly, which flatters a contract-heavy chain.
- Receive-side activity is passive. An address can be scored as retained because someone sent it dust.
- Incentive cohorts are not comparable to organic ones. Campaign periods produce enormous cohorts of addresses created to qualify for a reward.
- Comparison against product-analytics benchmarks is invalid. Different identity units, so the numbers are not the same statistic.
- Custodial users are invisible. Someone transacting through an exchange never appears in any cohort, so retention describes only self-custodial participation.
Cross-Network and Provider Comparison
The rotation bias differs enough between ledger models that cross-chain retention comparison mostly measures wallet conventions.
UTXO chains encourage a new address per receive, and privacy guidance actively recommends it, so address-level retention on Bitcoin understates participant retention severely. Account chains reuse a single address indefinitely by default, so address-level retention on Ethereum is much closer to participant retention. Comparing the two directly will show the account chain retaining better even if participant behavior is identical.
Chains with negligible fees accumulate large populations of automated addresses that either retain perfectly or never return, both of which distort the curve away from human behavior. Chains with meaningful fees have less of this.
Custodial concentration is the confounder nobody can correct for. A chain where most users hold through exchanges has most of its participant activity invisible to any on-chain cohort analysis, and the share held custodially differs substantially between assets.
Advanced Analytical Methods
Entity-level cohorts
Running the analysis on clustered entities instead of raw addresses recovers a portion of rotated addresses. The gap between the address curve and the entity curve is itself a useful estimate of how much rotation is occurring on that chain.
Value-weighted retention
Weighting each retained address by the value it transacts distinguishes a cohort that retained many trivial addresses from one that retained fewer economically significant ones. Airdrop cohorts look dramatically worse under value weighting, which is the correct outcome.
Resurrection tracking
Classic retention scores an address inactive in period t+n as churned even if it returns at t+n+1. Tracking returns after a gap separates genuine abandonment from intermittent usage, which matters for assets held rather than spent.
Cohort triangle presentation
Presenting every cohort against every lag in a triangle, rather than a single averaged curve, exposes whether retention is improving over successive cohorts, which is the comparison the metric supports best.
Practical Checklist
- I stated whether the curve is classic or cumulative.
- I stated whether activity means sending, receiving, or either.
- I excluded contract addresses or reported both curves.
- I computed entity-level retention alongside address-level.
- I checked the cohort period for incentive campaigns.
- I compared cohorts against each other, not an external benchmark.
- I reported the level explicitly as a lower bound.
- I noted that custodial participants are absent entirely.
Frequently Asked Questions
Why is on-chain retention always a lower bound?
Because a returning participant who uses a fresh address is scored as churned. Hierarchical deterministic wallets derive a new address for each receive without the user being aware, so address-based retention is biased downward by construction. The size of the understatement varies by chain and wallet convention and cannot be measured directly.
What is the difference between classic and cumulative retention?
Classic retention counts an address as retained only if it is active in exactly the target period. Cumulative counts it if it was active at any point through that period, so cumulative is always higher. The two produce very different-looking curves from identical data and are frequently compared as though interchangeable.
Should contract addresses be included in retention cohorts?
Generally no, or at least reported separately. Contracts are invoked continuously and retain almost perfectly, so on a contract-heavy chain their inclusion can dominate the curve and make retention look far better than participant behavior warrants.
Can on-chain retention be compared to product analytics benchmarks?
No. A software product measures stable user ids and a chain measures rotating addresses, so the two are not the same statistic. On-chain figures will look catastrophic against product benchmarks for purely mechanical reasons unrelated to how the network is performing.
How does entity clustering improve retention analysis?
Grouping addresses that provably share ownership, most commonly through the common-input heuristic, recovers a portion of rotated addresses. Clustered retention is higher than address retention and is still a lower bound. The gap between the two curves is itself a useful estimate of how much rotation is occurring on that chain.
Why do incentive-period cohorts retain so poorly?
Campaign periods produce enormous cohorts of addresses created solely to qualify for a reward, used once, and abandoned. The signature is a curve that never flattens. Comparing such a cohort against an organic one measures the campaign, not the network.
Are custodial users visible in on-chain retention?
No. Someone transacting through an exchange never appears in any on-chain cohort, so retention describes self-custodial participation only. The share of an asset held custodially differs substantially between assets, which makes cross-asset retention comparison unreliable.
What window length should a retention cohort use?
One matched to how often the behaviour being measured would naturally recur. A weekly window suits activity people do often, such as trading or gaming, and will show most participants as churned if applied to something done a few times a year, such as rebalancing a long-term position. Too long a window hides churn by giving everyone many chances to return. The window is the single most consequential parameter in a retention chart and is frequently omitted from the label.
How does a chain's fee level affect measured retention?
High fees suppress it mechanically, independent of whether anyone lost interest. Returning to a protocol requires paying to transact, so during expensive periods users with small positions rationally stay away and are recorded as churned. When fees fall they may return, producing a recovery that is a response to cost rather than to the product. Cohorts formed during cheap periods and measured through an expensive one therefore look worse than cohorts formed at other times, which is a comparison artefact rather than a finding.
References
These sources should be reviewed during editorial verification. They support data structures and methods, not the hypothetical conclusion. Provider formulas, chain rules, and APIs can change. Confirm current documentation before publication.
- Ethereum.org: Transactions: Ethereum transaction fields and execution.
- Ethereum.org: Gas and Fees: Gas, base fees, tips, and block-space demand.
- Bitcoin Developer Guide: Transactions: UTXO transaction construction and spending.
- Coin Metrics: Transaction Metrics: Transaction-count definitions.
- Coin Metrics: New Addresses: New and funded address methodology.
- Coin Metrics: Network Data Glossary: Cross-network address, account, ledger, and UTXO definitions.
- Dune: Data Explorer and Raw Tables: Blocks, transactions, logs, traces, and decoded data.
- Dune: Curated Data Overview: Cross-chain normalized datasets.