moonetix / referral-engine
Referral codes, attribution with fraud checks, commission plans and an append-only commission ledger. JavaScript and PHP.
Requires
- php: >=8.1
Requires (Dev)
None
Suggests
- ext-pdo: For PdoStore and the SQL schemas in schema/
Provides
None
Conflicts
None
Replaces
None
README
Referral codes, attribution with fraud checks, commission plans and an append-only commission ledger. Same behavior in JavaScript and PHP.
Maintained by Moonetix.
Referral programs in apps, SaaS products, games and communities tend to break in the same places. A bonus paid at sign-up gets farmed with second accounts. Commission is paid on rewards that are reversed two weeks later. A clawback takes back more than the referrer ever received, or nothing at all. A friend types an O where the code has a 0 and the referral is lost.
This library covers the parts that have to be exact: codes people can read aloud, attribution with explainable guards, commission plans with caps, and a ledger where every commission links to the earning that produced it, so a reversal takes back exactly that commission and nothing more.
- JavaScript: ESM, zero dependencies, TypeScript declarations, Node 20+.
- PHP: 8.1+, zero dependencies. PDO only if you use
PdoStore. - One spec: both suites run the same test vectors, 153 cases, including 16 ledger scenarios that also run on a real SQLite database.
Commission is earned only from the referred user's own confirmed earnings and is paid on top of them. There is no sign-up or invite bonus, by design: a reward for creating an account is the easiest money a referral farm can collect.
Try it
Clone the repository and run the demo. It needs Node 20 or later and installs nothing:
git clone https://github.com/moonetix/referral-engine.git cd referral-engine npm run demo # or: node examples/demo.mjs
It walks through one referrer and four sign-ups with a tiered plan, a 14-day hold, a chargeback and three payouts, using only the public API (examples/demo.mjs). Part of the output:
3. Four people sign up with it
u_ben attributed, referred by u_ana
u_cleo attributed, referred by u_ana
u_dan attributed, referred by u_ana
u_eve blocked: same_device (The new account signed up on a device the referrer has used (1 shared).)
4. Referred users earn; Ana's commission is added on top
2026-01-02 u_ben earns $20.00 -> Ana gets $2.00 (10.00%), available 2026-01-16
2026-01-03 u_cleo earns $30.00 -> Ana gets $3.00 (10.00%), available 2026-01-17
2026-01-04 u_dan earns $40.00 -> Ana gets $6.00 (15.00%), available 2026-01-18
2026-01-05 u_ben earns $10.00 -> Ana gets $1.50 (15.00%), available 2026-01-19
5. Chargeback: Dan's $40.00 is reversed after the hold
2026-01-22 tx_3 reversed -> $6.00 clawed back from Ana
balance on 2026-01-22: pending $0.00, available $6.50, total $6.50
6. Payouts never take more than the balance
2026-01-26 payout $15.00 -> refused, insufficient_balance: available balance is 650, payout is 1500
2026-01-26 payout $6.00 -> recorded
2026-01-23 payout $5.00 dated earlier -> refused, insufficient_balance: available balance is 50, payout is 500
The referral lifecycle
flowchart TD
A["Touches: link visits, typed codes"] --> B["attribute(): window, model, guard checks"]
B -->|blocked or no touch| X[No referrer]
B -->|attributed or review| C["attach(): one referrer per user, for good"]
C --> D["recordEarning(): referee's confirmed earning"]
D -->|plan, caps, rounded down once| E[Accrual, pending]
E -->|holdSeconds pass| F[Available]
F --> G["recordPayout()"]
D -.->|earning reversed| R["reverseEarning(): never more than accrued"]
R -.->|in hold: cancelled| E
R -.->|released: clawed back| F
Loading
| Function | What it does |
|---|---|
generateCode(options) |
Random code from an unambiguous 29-character alphabet, no modulo bias, optional check character |
normalizeCode, isValidCode, formatCode |
Clean up typed input (case, spaces, hyphens), validate length and check character, group for display |
createUniqueCode(exists, options) |
Retry on collision against your own lookup |
attribute({ signup, touches, referrers, rules }) |
Pick the referrer: attribution window, first or last touch, typed-code grace period, guard checks |
selfReferral, sameDevice, sameIp, samePayoutDestination |
Built-in guard checks; any function of the same shape works too |
definePlan(config) |
Validate a flat, percentage or tiered plan with duration and caps |
commissionFor(plan, amount, stats) |
Commission for one earning before caps, for previews and offer pages |
new ReferralEngine({ store, plan, ... }) |
attach, recordEarning, reverseEarning, recordPayout, recordAdjustment, balance, ledger |
MemoryStore, SqliteStore (JS), PdoStore (PHP) |
Storage adapters. Any object with five methods works (store interface) |
fraudSignals({ referrer, referees, edges, now }) |
Score with readable reasons: shared devices, networks and payout destinations, bursts, earn-then-vanish, reversal rate, loops |
findRings(edges) |
Groups of accounts that refer each other in a loop |
ipPrefix(ip, { ipv4Prefix, ipv6Prefix }) |
The network an address belongs to, as CIDR text |
Quick start
The JavaScript package is on npm and the PHP package is on Packagist:
npm install @moonetix/referral-engine composer require moonetix/referral-engine
JavaScript
import { MemoryStore, ReferralEngine, attribute, formatCode, generateCode } from '@moonetix/referral-engine'; const DAY = 86400; const engine = new ReferralEngine({ store: new MemoryStore(), plan: { type: 'percentage', rateBps: 1000, durationSeconds: 365 * DAY, perRefereeCap: 50000 }, holdSeconds: 14 * DAY, }); // 1. Every user gets a short code to share. Store it with a UNIQUE constraint. const code = generateCode(); console.log(formatCode(code).length); // -> 9 // 2. At sign-up, pick the referrer from the touches you recorded (link visits, typed codes). const at = 1767225600; // 2026-01-01 00:00 UTC const result = attribute({ signup: { userId: 'u_2001', at, deviceIds: ['dev_b'], ips: ['198.51.100.23'] }, touches: [{ referrerId: 'u_1001', code: 'WPEAJ39T', at: at - 3600 }], referrers: { u_1001: { deviceIds: ['dev_a'], ips: ['203.0.113.5'] } }, }); console.log(result.decision, result.referrerId); // -> attributed u_1001 if (result.referrerId) await engine.attach({ refereeId: 'u_2001', referrerId: result.referrerId, at }); // 3. The friend's own reward is confirmed (for example a credited postback): 10% on top. const earned = await engine.recordEarning({ earningId: 'tx_9001', refereeId: 'u_2001', amount: 2500, at: at + DAY }); console.log(JSON.stringify(earned.commissions)); // -> [{"level":1,"referrerId":"u_1001","amount":250,"availableAt":1768521600}] console.log(JSON.stringify(await engine.balance('u_1001', at + DAY))); // -> {"pending":250,"available":0,"total":250,"uncollected":0} // 4. The reward is reversed before the hold ends: the commission is cancelled, once. const reversed = await engine.reverseEarning({ earningId: 'tx_9001', at: at + 5 * DAY }); console.log(JSON.stringify(reversed.clawbacks)); // -> [{"level":1,"referrerId":"u_1001","amount":250,"uncollected":0}] console.log(JSON.stringify(await engine.balance('u_1001', at + 30 * DAY))); // -> {"pending":0,"available":0,"total":0,"uncollected":0}
PHP
<?php require __DIR__ . '/vendor/autoload.php'; use Moonetix\ReferralEngine\MemoryStore; use Moonetix\ReferralEngine\Referral; use Moonetix\ReferralEngine\ReferralEngine; const DAY = 86400; $engine = new ReferralEngine([ 'store' => new MemoryStore(), 'plan' => ['type' => 'percentage', 'rateBps' => 1000, 'durationSeconds' => 365 * DAY, 'perRefereeCap' => 50000], 'holdSeconds' => 14 * DAY, ]); // 1. Every user gets a short code to share. Store it with a UNIQUE constraint. $code = Referral::generateCode(); echo strlen(Referral::formatCode($code)), "\n"; // -> 9 // 2. At sign-up, pick the referrer from the touches you recorded (link visits, typed codes). $at = 1767225600; // 2026-01-01 00:00 UTC $result = Referral::attribute([ 'signup' => ['userId' => 'u_2001', 'at' => $at, 'deviceIds' => ['dev_b'], 'ips' => ['198.51.100.23']], 'touches' => [['referrerId' => 'u_1001', 'code' => 'WPEAJ39T', 'at' => $at - 3600]], 'referrers' => ['u_1001' => ['deviceIds' => ['dev_a'], 'ips' => ['203.0.113.5']]], ]); echo $result['decision'], ' ', $result['referrerId'], "\n"; // -> attributed u_1001 if ($result['referrerId'] !== null) { $engine->attach(['refereeId' => 'u_2001', 'referrerId' => $result['referrerId'], 'at' => $at]); } // 3. The friend's own reward is confirmed (for example a credited postback): 10% on top. $earned = $engine->recordEarning(['earningId' => 'tx_9001', 'refereeId' => 'u_2001', 'amount' => 2500, 'at' => $at + DAY]); echo json_encode($earned['commissions']), "\n"; // -> [{"level":1,"referrerId":"u_1001","amount":250,"availableAt":1768521600}] echo json_encode($engine->balance('u_1001', $at + DAY)), "\n"; // -> {"pending":250,"available":0,"total":250,"uncollected":0} // 4. The reward is reversed before the hold ends: the commission is cancelled, once. $reversed = $engine->reverseEarning(['earningId' => 'tx_9001', 'at' => $at + 5 * DAY]); echo json_encode($reversed['clawbacks']), "\n"; // -> [{"level":1,"referrerId":"u_1001","amount":250,"uncollected":0}] echo json_encode($engine->balance('u_1001', $at + 30 * DAY)), "\n"; // -> {"pending":0,"available":0,"total":0,"uncollected":0}
Without Composer, require php/autoload.php from this repository instead of vendor/autoload.php.
Amounts are integers in your smallest unit: cents, points, or micro-dollars. JavaScript takes safe integers (up to 2^53 - 1) and PHP takes the same range, so a value means the same thing on both sides. Rates are basis points: 1000 is 10%. Instants are Unix seconds. IDs can be strings or integers and always come back as strings. Every error carries a stable code (err.code in JavaScript, $e->errorCode in PHP), such as already_referred or insufficient_balance.
Codes people can type
The default alphabet is 23456789ABCDEFGHJKMNPQRSTVWXY: 29 symbols without 0, O, 1, I, L, U and Z. normalizeCode accepts lowercase, spaces and hyphens, so wpea-j39t and WPEA J39T both become WPEAJ39T. With a custom alphabet that has 0 and 1 but not O, I or L, those letters are read as the digits.
With checkChar: true a ninth character is added. Because 29 is prime, a weighted sum modulo 29 catches every single wrong character and every swap of two neighbors, so isValidCode can reject a typo before you look the code up. The test suites check that exhaustively.
How often codes collide, for random 8-character codes (29^8 = 500,246,412,961 possibilities):
| Codes issued | Chance one new code hits an existing one | Chance of at least one collision while issuing them all |
|---|---|---|
| 100,000 | 1 in 5,000,000 | about 1% |
| 1,000,000 | 1 in 500,000 | about 63% |
| 10,000,000 | 1 in 50,000 | almost certain |
Collisions will happen on any program that grows, so createUniqueCode retries against your lookup, and the referral_codes.code column in the schemas is UNIQUE. Insert, and on a duplicate-key error generate again. With 10 characters, the chance of any collision across a million codes falls to about 0.1%.
Configuration reference
Commission plan (definePlan, or the plan option of the engine)
| Option | Type | Default | Notes |
|---|---|---|---|
type |
'percentage' | 'flat' | 'tiered' |
required | |
rateBps |
integer 0 to 10,000 | required for percentage |
Share of the referee's earning, rounded down |
amount |
integer | required for flat |
Fixed commission per qualifying earning |
trigger |
'first' | 'every' |
'first' |
flat only. first pays once per referee, again only if that commission was fully reversed |
basis |
'referees' | 'volume' |
'referees' |
tiered only. Qualified referees (with a net confirmed earning), or the sum of their confirmed earnings net of reversals, measured before the current earning |
tiers |
[{ from, rateBps }] |
required for tiered |
Starts at from: 0, strictly increasing |
minEarning |
integer | 1 | Smaller earnings produce no commission and do not qualify a referee |
durationSeconds |
integer or null |
null (lifetime) |
Commission stops this long after attribution, for example 31,536,000 for one year |
perEarningCap |
integer or null |
null |
Ceiling for one earning |
perRefereeCap |
integer or null |
null |
Lifetime ceiling per referee, net of clawbacks |
perReferrerCap |
{ amount, periodSeconds } or null |
null |
Ceiling per referrer per fixed UTC window, for example 2,592,000 seconds |
Engine (new ReferralEngine(options))
| Option | Default | Notes |
|---|---|---|
store |
required | MemoryStore, SqliteStore, PdoStore or your own |
plan |
required | A plan config or the result of definePlan |
holdSeconds |
0 | An accrual stays pending this long. Set it at least as long as the hold on the referee's own reward |
allowNegativeBalance |
true |
false stops a clawback of released commission at the available balance; the rest is reported as uncollected |
availableBalance(referrerId, at) |
ledger balance | The balance used for that floor when you move released commission into another wallet |
multiLevel |
null |
{ levels: [bps, ...], acknowledgeRegulatoryRisk: true }. See Multi-level commissions |
Attribution rules (attribute({ rules }))
| Option | Default | Notes |
|---|---|---|
model |
'last' |
'first' or 'last' touch. On equal times, last takes the later array item and first the earlier |
windowSeconds |
2,592,000 (30 days) | Oldest touch that still counts at sign-up |
typedCodeGraceSeconds |
604,800 (7 days) | A code with source: 'typed' may arrive this long after sign-up. Link touches after sign-up never count |
checks |
all four built-ins | Functions or descriptors such as { check: 'sameIp', ipv4Prefix: 24 }. An empty array turns checks off |
| Built-in check | Default action | Fires when |
|---|---|---|
selfReferral |
block |
The touch belongs to the new account itself |
sameDevice |
block |
The new account shares a device ID with the referrer |
sameIp |
review |
Both used the same IPv4 address (ipv4Prefix: 32) or IPv6 /64 (ipv6Prefix: 64) |
samePayoutDestination |
block |
Both use the same payout destination |
Each built-in takes action ('block' or 'review') to override its default; sameIp also takes ipv4Prefix and ipv6Prefix.
Candidates are tried in model order. A candidate with any block reason is skipped and the next referrer is tried; review reasons keep the referrer and set decision: 'review'. The result lists every reason with the referrer it applies to, so support can explain the outcome.
Codes: length (8), alphabet (the 29 symbols), checkChar (false), randomBytes (crypto.getRandomValues or random_bytes), maxAttempts for createUniqueCode (10). formatCode takes groupSize (4) and separator ('-').
Fraud signals (fraudSignals({ options })): ipv4Prefix (24), ipv6Prefix (64), networkClusterSize (3), burstSize (5), burstWindowSeconds (3,600), vanishMinCount (2), vanishEarnWithinSeconds (259,200), vanishInactiveSeconds (1,209,600), reversalRateBps (3,000), reversalMinEarned (1), reviewAt (30), highAt (60), and weights, an object keyed by signal code with values 0 to 100.
The ledger
Every change is an appended entry. Nothing is updated or deleted, and the reference schemas enforce that with triggers.
| Field | Meaning |
|---|---|
key |
Idempotency key: accrual:<level>:<earningId>, a clawback key per reversal ID, payout:<id>, adjustment:<id> |
type |
accrual, clawback, payout or adjustment |
referrerId, refereeId, earningId, level |
Who earns, from whom, from which earning, and at which level (1 unless multi-level is on) |
amount |
Signed: accruals add, clawbacks and payouts subtract, adjustments go either way |
baseAmount |
The referee earning behind an accrual, or the part of it a clawback reversed (negative) |
uncollected |
Clawbacks only: the part not taken back because of the balance floor |
at, availableAt |
When it happened, and when an accrual stops being pending |
recordEarning returns status: 'accrued', 'duplicate' (same earningId again, nothing written) or 'none' with a reason: no_referrer, before_referral, expired or below_minimum. When a cap applies, capped names it. A zero commission is still recorded when a cap or a first trigger brings it to zero, so the earning counts toward tiers and a repeat is still a duplicate.
reverseEarning takes the reversed part of the referee's earning (amount, or the rest when omitted) and a reversalId (the earning ID by default, which makes a repeated full reversal a no-op). It claws back the same share of each commission built on that earning, rounded down, and the last reversal takes exactly what is left. A commission still in its hold is cancelled outright; that never pushes a balance below zero.
Store interface. MemoryStore is for tests. SqliteStore (import from referral-engine/sqlite) takes a node:sqlite DatabaseSync or a better-sqlite3 handle. PdoStore takes any PDO connection. Your own store needs:
| Method | Contract |
|---|---|
getReferral(refereeId) |
The referral or null |
insertReferral(referral) |
false when the referee already has one |
listEntries({ referrerId?, refereeId?, earningId? }) |
Matching entries in insertion order |
appendEntries(entries) |
All or nothing; false, writing nothing, when a key exists |
withLock(key, fn) |
Run fn without interleaving writes for the same key. Optional in JavaScript: without it the engine queues its calls per key, which is enough only while a single process writes to the store |
Schemas: schema/postgresql.sql, schema/mysql.sql, schema/sqlite.sql. Amount and time columns are BIGINT. CI runs every ledger vector against the SQLite schema in both languages, and loads the PostgreSQL and MySQL files into PostgreSQL 17, MySQL 8.4 and MariaDB 11.4 for the parallel payout test; review them against your own server version before you use them.
import { readFileSync } from 'node:fs'; import { DatabaseSync } from 'node:sqlite'; import { ReferralEngine } from '@moonetix/referral-engine'; import { SqliteStore } from '@moonetix/referral-engine/sqlite'; const db = new DatabaseSync(':memory:'); // a file path in production db.exec(readFileSync(new URL(import.meta.resolve('@moonetix/referral-engine/schema/sqlite.sql')), 'utf8')); const engine = new ReferralEngine({ store: new SqliteStore(db), plan: { type: 'percentage', rateBps: 500 } }); await engine.attach({ refereeId: 'u_2001', referrerId: 'u_1001', at: 1767225600 }); // The same postback delivered three times at once still accrues once. const results = await Promise.all([1, 2, 3].map(() => engine.recordEarning({ earningId: 'tx_9001', refereeId: 'u_2001', amount: 4000, at: 1767229200 }))); console.log(results.map((r) => r.status).join(' ')); // -> accrued duplicate duplicate console.log(db.prepare('SELECT SUM(amount) AS total FROM referral_ledger').get()?.total); // -> 200
<?php require __DIR__ . '/vendor/autoload.php'; use Moonetix\ReferralEngine\PdoStore; use Moonetix\ReferralEngine\ReferralEngine; $pdo = new PDO('sqlite::memory:'); // or mysql:/pgsql: with schema/mysql.sql or schema/postgresql.sql $pdo->exec(file_get_contents(__DIR__ . '/vendor/moonetix/referral-engine/schema/sqlite.sql')); $engine = new ReferralEngine(['store' => new PdoStore($pdo), 'plan' => ['type' => 'percentage', 'rateBps' => 500]]); $engine->attach(['refereeId' => 'u_2001', 'referrerId' => 'u_1001', 'at' => 1767225600]); // The same postback delivered twice accrues once. foreach ([1, 2] as $attempt) { $r = $engine->recordEarning(['earningId' => 'tx_9001', 'refereeId' => 'u_2001', 'amount' => 4000, 'at' => 1767229200]); echo $r['status'], "\n"; } // -> accrued // -> duplicate echo $pdo->query('SELECT SUM(amount) FROM referral_ledger')->fetchColumn(), "\n"; // -> 200
node:sqlite works without a flag from Node 22.13; 22.5 to 22.12 need --experimental-sqlite. PdoStore runs each engine call in one transaction. SQLite allows one writer at a time, so that is enough there. On PostgreSQL and MySQL a transaction alone would let two workers read the same balance, so withLock also takes a lock named after its key before the first read: pg_advisory_xact_lock on PostgreSQL, held until the transaction ends, and GET_LOCK on MySQL and MariaDB, released after the commit. Two payouts for one referrer, or two copies of one earning, then run one after the other. Keep PostgreSQL at READ COMMITTED, its default, for these connections. On MySQL a call that waits more than 10 seconds for its lock throws conflict, and the engine should be called outside a transaction of your own: a named lock is released when the call returns, not when your transaction commits. At MySQL's default REPEATABLE READ, an earning that waited for another call of the same referrer still measures caps and tiers on the rows it saw when it started; use READ COMMITTED if a cap must hold exactly under parallel earnings. CI runs a parallel payout test against PostgreSQL, MySQL and MariaDB: eight connections ask for the same balance at the same moment, and exactly one of them is paid.
Fraud signals
Most referral fraud is one person, or a small group, playing both sides. The useful checks compare the referrer with the accounts they referred, and the referred accounts with each other. fraudSignals does that for one referrer and returns a score with a sentence per signal, for a review queue rather than an automatic ban.
import { fraudSignals } from '@moonetix/referral-engine'; const DAY = 86400; const report = fraudSignals({ referrer: { id: 'u_1001', deviceIds: ['dev_a'], ips: ['203.0.113.5'], payoutDestinations: ['paypal:5f1c'] }, referees: [ { id: 'u_2001', deviceIds: ['dev_b'], ips: ['198.51.100.23'], payoutDestinations: ['paypal:5f1c'], signedUpAt: 0, firstEarningAt: 3600, lastActiveAt: 7200, earned: 3000, reversed: 3000 }, { id: 'u_2002', deviceIds: ['dev_c'], ips: ['198.51.100.24'], payoutDestinations: ['paypal:91aa'], signedUpAt: 600, firstEarningAt: 4000, lastActiveAt: 8000, earned: 2800, reversed: 1400 }, { id: 'u_2003', deviceIds: ['dev_d'], ips: ['192.0.2.77'], payoutDestinations: ['paypal:0c3e'], signedUpAt: 20 * DAY, firstEarningAt: 22 * DAY, lastActiveAt: 40 * DAY, earned: 4000 }, ], now: 40 * DAY, }); console.log(report.score, report.level); // -> 75 high for (const s of report.signals) console.log(`${s.code}: ${s.message}`); // -> shared_payout_with_referrer: 1 referred account cashes out to a payout destination the referrer also uses. // -> earn_then_vanish: 2 referred accounts earned within 3 days of signing up and have been inactive for 14 days or more. // -> high_reversal_rate: Reversals are 44.89% of referred earnings (4400 of 9800).
The PHP version is examples/fraud-signals.php and prints the same lines.
| Signal | Default weight | Fires when |
|---|---|---|
shared_payout_with_referrer |
40 | A referee cashes out to a destination the referrer uses |
shared_device_with_referrer |
30 | A referee used one of the referrer's devices |
shared_network_with_referrer |
10 | A referee used the referrer's /24 or /64 |
shared_payout_among_referees |
30 | Two or more referees share a payout destination |
shared_device_among_referees |
20 | Two or more referees share a device |
shared_network_among_referees |
10 | networkClusterSize (3) or more referees share a /24 or /64 |
signup_burst |
15 | burstSize (5) or more referees signed up within burstWindowSeconds (1 hour) |
earn_then_vanish |
15 | vanishMinCount (2) or more referees earned within 3 days of sign-up and have been inactive for 14 days |
high_reversal_rate |
20 | Reversals reach reversalRateBps (30%) of the tree's earnings |
referral_ring |
40 | edges contain a loop that touches this referrer or a referee |
The score is the sum of weights, capped at 100. level is review from 30 (reviewAt) and high from 60 (highAt). Every threshold and weight is an option.
When a tree scores high, handle it as one case, the way the referral fraud guide describes: freeze pending commission and cashouts in the cluster instead of banning, list which accounts share what, compare what they did and how much was reversed, and decide per account. A real friend keeps their rewards even if the referrer cheated. Families and roommates share devices and Wi-Fi, and a streamer's audience arrives in a burst, so give people a human appeal.
Multi-level commissions
Off by default. With multiLevel: { levels: [300], acknowledgeRegulatoryRisk: true } the referrer's own referrer also earns 3% of the same earning, and so on for up to four extra levels. Higher levels use their flat rate on the referee's earning, never on commission, with no tiers or caps. Without acknowledgeRegulatoryRisk: true the constructor throws multi_level_not_acknowledged.
Warning
Paying people for the referrals of their referrals is how pyramid schemes are built, and many jurisdictions regulate or prohibit schemes where rewards come mainly from recruiting rather than from a product. The EU Unfair Commercial Practices Directive (2005/29/EC, Annex I, point 14) lists pyramid promotional schemes among the practices that are unfair in all circumstances, and the US FTC publishes business guidance on multi-level marketing. Multi-level commission also rewards account rings far more than real advocates. Pay one level, and get legal advice for every market you serve before you change that. This section is not legal advice.
How it works
- A code is drawn byte by byte from a cryptographic source. Bytes at or above the largest multiple of the alphabet size are skipped, so every symbol is equally likely.
- You store touches as they happen: a link visit with the code, or a code typed at or after sign-up.
attributekeeps the touches inside the window, orders them by the model, and runs the guard checks on each candidate referrer until one is not blocked. attachstores one referral per referee. A second call with the same referrer is a no-op; a different referrer throwsalready_referred, and a chain that would loop throwsreferral_cycle.- When the referee's own reward is confirmed,
recordEarningmeasures the referrer's tier, applies the plan, then the per-earning, per-referee and per-period caps, and appends one accrual keyed by the earning ID. The commission is computed as one integer product and rounded down once. balance(referrerId, at)replays the referrer's entries up toat: accruals still in their hold are pending, the rest is available, minus clawbacks and payouts.reverseEarningreads what was accrued for that earning and what was already clawed back, and appends a clawback for the difference between the new cumulative share and the old one. It can never exceed the original commission.- Each call runs inside the store's
withLock, or inside the engine's own queue per key when a JavaScript store has none, and the ledger's unique key makes a concurrent duplicate fail instead of double-counting.
Pitfalls
- Paying on sign-up. A sign-up takes seconds to fake. Pay from the referee's confirmed earnings, as this library does, or after a qualifying action that a fake account finds costly.
- Accruing on credited instead of confirmed earnings. If the referrer can cash out before the referee's reward clears its hold, a reversed reward has already paid commission. Call
recordEarningwhen the referee's reward is confirmed, and setholdSecondsat least as long as your reward hold. Reward hold periods covers how long that should be. - Partial reversals with one ID. A reversal ID is an idempotency key. Use the network's transaction ID for a full reversal, and a distinct ID for each partial reversal of the same earning.
- Recomputing commission at reversal time. Rates and tiers change. The ledger stores the commission that was actually accrued, and clawbacks are measured against that.
- Changing the referrer later. Support requests to move a referral are a common fraud path.
attachrefuses it; do the same in your admin tools. - Treating a shared IP as proof. Carrier-grade NAT, campuses and offices put many people behind one address. That is why
sameIpreviews instead of blocking, and why network weights are low infraudSignals. - Comparing raw payout destinations. Normalize first (trim, lowercase emails, strip formatting from wallet addresses), then hash, and compare the hashes. Never send raw payout details to a fraud tool you do not need to.
- Commission on commission. The base is always the referee's own earning. Referral commission never counts as earnings for the next level up.
- Showing referees to referrers. Show a username, a status and the referrer's own reward. Never the friend's email or activity.
- Rewards for store actions. Never tie a referral reward to a rating or review; Google Play's policy forbids incentives for them. On iOS, App Review Guideline 5.1.2(v) requires contact invites to be chosen one by one by the user, with no Select All. Referral program design covers the store rules.
- Terms written after launch. One account per person, no self-referrals, no paying people to sign up, commission depends on confirmed earnings, and clawbacks are possible. Rewards site terms of service walks through the wording.
Errors you will meet
| Code | Thrown by | What to do |
|---|---|---|
already_referred |
attach |
The referee already has a different referrer. Keep the first one; a repeat with the same referrer is a no-op and does not throw |
referral_cycle, self_referral |
attach |
The pair would loop or is one user. Drop the referral |
insufficient_balance |
recordPayout |
The message gives the available balance. Pending accruals cannot be paid out until holdSeconds pass. Payouts, clawbacks and negative adjustments already in the ledger always count, even when the new payout carries an earlier at |
conflict |
any ledger write | Another worker wrote the same ledger key between the check and the insert, usually because the store's withLock does not cover your workers. Retry the call: a repeated earning, payout or adjustment ID then returns status: 'duplicate' |
invalid_plan |
definePlan, the engine constructor |
The message names the field, for example tiers that do not start at from: 0 |
multi_level_not_acknowledged |
the engine constructor | multiLevel was set without acknowledgeRegulatoryRisk: true |
code_space_exhausted |
createUniqueCode |
No free code after maxAttempts. Use longer codes |
invalid_code, alphabet_not_prime |
check character helpers | A character outside the alphabet, or checkChar: true with an alphabet whose size is not prime |
invalid_argument, invalid_ip, overflow |
any call | A wrong type, an unparseable IP, or an amount or time above 2^53 - 1 |
ERR_UNKNOWN_BUILTIN_MODULE for node:sqlite means Node is too old for the built-in SQLite module (see The ledger); pass a better-sqlite3 handle or use your own store there.
Tests
npm test # node --test: shared vectors, SQLite store, API tests, every example php php/tests/run.php # shared vectors on MemoryStore and PdoStore (SQLite), PHP-specific checks php php/tests/concurrency.php # parallel payouts on a real database, skipped without REFERRAL_TEST_DSN
php/tests/concurrency.php takes REFERRAL_TEST_DSN (pgsql:, mysql: or sqlite:) with REFERRAL_TEST_USER and REFERRAL_TEST_PASSWORD. It drops and recreates the referral tables there, so point it at a throwaway database. Worker processes with their own connections then call recordPayout at the same moment: one balance must be paid exactly once, and payouts for different referrers must all go through.
test-vectors/vectors.json holds 153 cases: code generation from fixed random bytes, check characters, IPv4 and IPv6 prefixes, every attribution rule, plan validation, commission math up to 2^53 - 1, fraud signals and 16 ledger scenarios (113 checked steps) with caps, tiers, holds, partial reversals, the balance floor, payouts dated out of order and multi-level chains. Every file in examples/ runs in the tests, and its output must match the // -> comments, which are the same code blocks you see in this README. The demo (examples/demo.mjs) has its own test that checks its exit code and key output lines.
Further reading
- How to prevent referral fraud on a rewards site: schemes, signals, payout rules and cluster review
- Referral program design for apps: structures, when to pay, caps, attribution and store rules
- Reward hold periods: pending, on hold and available, and how long to hold
- Stop multi-accounting and VPN abuse and KYC for rewards sites
- Rewards site terms of service
About Moonetix
Moonetix is an affiliate network. Publishers add its offerwall to an app, game, website, bot or community, and users earn the publisher's own currency by completing offers. Publisher accounts: moonetix.com/register.
Other open source from Moonetix: reward-economy-kit, country-tiers, datacenter-ip-ranges, offerwall-fraud-playbook, signup-guard, gamification-kit, awesome-offerwalls, offerwall-postback-handlers.
License
MIT. See LICENSE.