Cohort Retention for On-Chain Applications
Build address-based retention cohorts with explicit entry actions and return windows, while handling partial history and avoiding claims about individual people.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Retention compares a defined cohort with later qualifying activity. In on-chain data, both cohort entry and return behaviour need explicit rules because addresses do not automatically map to people.
Define entry and return separately
A first qualifying contract interaction can define entry, while a later interaction can define return. Specify rolling or calendar windows and network scope. If historical coverage starts recently, first observed activity may not be true first activity. Keep that limitation visible in the cohort definition.
Worked example: a seven-day return
One hundred addresses first perform the selected action during a cohort week. Thirty perform the return action in the declared next-seven-day window. Address-based retention is thirty percent for that definition. It does not establish that thirty distinct people returned or that the remaining addresses permanently stopped using the product.
Handle incomplete observation windows
Do not compare a fully matured cohort with one whose return window is still open without labelling it. Test address changes, automated accounts and missing historical ranges. Keep denominator rules stable across reports. A dashboard should expose the entry and return predicates so a rising retention line can be traced to behaviour rather than a silent methodology change.
A practical acceptance test
Create a hundred-address entry cohort with thirty qualifying returns, then a newer cohort whose return window is incomplete. Assert thirty percent for the matured fixture and an explicit partial state for the other. Remove earlier coverage and verify that first observed entry is not relabelled first-ever use without evidence.
Questions about the topic
Frequently asked questions
Can an unfinished cohort be compared directly with a mature one?
Only with a clear partial-window treatment.
Does first observed mean first ever?
Not when earlier history is outside coverage.
Standards & technical documentation