clockwork-press 0.2.2 → 0.2.3

package/dist/index.js

@@ -37,6 +37,10 @@ else if (job === 'log') {
     const { runLog } = await import('./jobs/log.js');
     await runLog();
 }
+else if (job === 'dividends') {
+    const { runDividends } = await import('./jobs/dividends.js');
+    await runDividends();
+}
 else if (job === 'holders') {
     const { readHolders } = await import('./holders.js');
     console.log(`holders: ${await readHolders()}`);
@@ -50,7 +54,7 @@ else if (job === 'launchcheck') {
     await runLaunchCheck();
 }
 else {
-    console.error(`unknown job: ${job} (use init | press | dry | doctor | claimcheck | holders | tgcheck | log | buys | quotecheck | launchcheck | handback <address>)`);
+    console.error(`unknown job: ${job} (use init | press | dry | doctor | claimcheck | holders | tgcheck | log | buys | quotecheck | launchcheck | dividends | handback <address>)`);
     process.exit(1);
 }
 export {};

package/dist/jobs/dividends.js

@@ -0,0 +1,293 @@
+// clockwork dividends: the holder side. some memestocks pay their holders in the stock. this job reads every
+// payout a known distributor made, groups them into drops, prices each drop at the time it landed, and writes
+// a public dataset the statement page and the leaderboard read: who pays, how much, to whom, worth what.
+// read-only; no key involved. the registry of distributors grows by hand and, later, from the airdrop signature.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createPublicClient, defineChain, fallback, formatUnits, http, parseAbi, parseAbiItem } from 'viem';
+// this job runs anywhere, with no machine config and no key: its own client on the public rpc (RPC_URL to override)
+const chain = defineChain({ id: 4663, name: 'Robinhood Chain', nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 }, rpcUrls: { default: { http: [process.env.RPC_URL || 'https://rpc.mainnet.chain.robinhood.com'] } } });
+const o = { retryCount: 6, retryDelay: 1500, timeout: 30_000 };
+const pub = createPublicClient({ chain, transport: process.env.RPC_URL_2 ? fallback([http(chain.rpcUrls.default.http[0], o), http(process.env.RPC_URL_2, o)]) : http(chain.rpcUrls.default.http[0], o) });
+const TOKENS = {
+    GME: { address: '0x1b0E319c6A659F002271B69dB8A7df2F911c153E', decimals: 18, feed: '0x27C71df6A64fB476468EdF256CF72c038baB5B67' },
+    USDG: { address: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168', decimals: 6 },
+};
+const DEFAULT_REGISTRY = [
+    { address: '0xe311d712bd0669896bcb47f38845ad71a641b8be', name: 'GameStop token, Diamond Drop', token: 'GME', memeToken: '0xc2362AfF2A2a4CC1f48cF3Dab2C4e2605eb94BA3', memeSymbol: 'GME (memecoin)', site: 'https://thegameneverstopped.com', note: 'hold $50+, lowest balance since the last drop is the base, a sell disqualifies, a streak multiplier to 2x' },
+];
+const ev = parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)');
+const feedAbi = parseAbi(['function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)', 'function getRoundData(uint80 roundId) view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)', 'function decimals() view returns (uint8)']);
+const GAP_BLOCKS = 70000n; // payouts closer than this belong to the same drop (about two hours at ten blocks a second)
+const CHUNK = 10000000n;
+const readJson = (p, d) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return d;
+} };
+const writeJson = (p, v) => writeFileSync(p, JSON.stringify(v, null, 1) + '\n');
+// the usd price of the pairing asset at a moment, from the chainlink feed's history: a binary search over the
+// current phase's rounds, cached per job run. null when the token has no feed.
+async function priceAt(sym, ts, cache) {
+    const t = TOKENS[sym];
+    if (!t?.feed)
+        return sym === 'USDG' ? 1 : null;
+    const key = `${sym}:${Math.floor(ts / 600)}`;
+    if (cache.has(key))
+        return cache.get(key);
+    try {
+        const dec = Number(await pub.readContract({ address: t.feed, abi: feedAbi, functionName: 'decimals' }));
+        const latest = await pub.readContract({ address: t.feed, abi: feedAbi, functionName: 'latestRoundData' });
+        const latestId = latest[0];
+        const phase = latestId >> 64n;
+        let lo = 1n, hi = latestId & ((1n << 64n) - 1n);
+        const at = async (agg) => pub.readContract({ address: t.feed, abi: feedAbi, functionName: 'getRoundData', args: [(phase << 64n) | agg] });
+        let best = Number(latest[1]) / 10 ** dec;
+        for (let i = 0; i < 40 && lo <= hi; i++) {
+            const mid = (lo + hi) / 2n;
+            let r;
+            try {
+                r = await at(mid);
+            }
+            catch {
+                lo = mid + 1n;
+                continue;
+            }
+            const upd = Number(r[3]);
+            if (!upd) {
+                lo = mid + 1n;
+                continue;
+            }
+            if (upd <= ts) {
+                best = Number(r[1]) / 10 ** dec;
+                lo = mid + 1n;
+            }
+            else
+                hi = mid - 1n;
+        }
+        cache.set(key, best);
+        return best;
+    }
+    catch {
+        cache.set(key, null);
+        return null;
+    }
+}
+async function marketCap(token) {
+    if (!token)
+        return null;
+    try {
+        const r = await fetch(`https://api.dexscreener.com/latest/dex/tokens/${token}`);
+        const j = await r.json();
+        const pairs = (j?.pairs || []).filter((p) => String(p.chainId).toLowerCase().includes('robinhood'));
+        const best = pairs.sort((a, b) => Number(b.liquidity?.usd || 0) - Number(a.liquidity?.usd || 0))[0];
+        const cap = best?.marketCap ?? best?.fdv;
+        return cap ? Number(cap) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runDividends() {
+    const dir = resolve(process.env.DIVIDENDS_DIR || 'data/dividends');
+    mkdirSync(join(dir, 'drops'), { recursive: true });
+    mkdirSync(join(dir, 'wallets'), { recursive: true });
+    const registry = readJson(join(dir, 'distributors.json'), DEFAULT_REGISTRY);
+    if (!existsSync(join(dir, 'distributors.json')))
+        writeJson(join(dir, 'distributors.json'), registry);
+    const state = readJson(join(dir, 'state.json'), {});
+    const index = readJson(join(dir, 'index.json'), { updatedAt: '', tokens: TOKENS, distributors: [], drops: [] });
+    const head = await pub.getBlockNumber();
+    const priceCache = new Map();
+    const walletShards = {};
+    const shardOf = (a) => a.slice(2, 4).toLowerCase();
+    const loadShard = (s) => (walletShards[s] ??= readJson(join(dir, 'wallets', `${s}.json`), {}));
+    let newDrops = 0;
+    for (const d of registry) {
+        const tok = TOKENS[d.token];
+        if (!tok) {
+            console.log(`[dividends] ${d.name}: unknown token ${d.token}, skipped`);
+            continue;
+        }
+        const key = `${d.address.toLowerCase()}:${d.token}`;
+        const fromBlock = BigInt(state[key] ?? 0) + (state[key] ? 1n : 0n);
+        if (fromBlock > head)
+            continue;
+        const logs = [];
+        for (let a = fromBlock; a <= head; a += CHUNK) {
+            const b = a + CHUNK - 1n > head ? head : a + CHUNK - 1n;
+            try {
+                const got = await pub.getLogs({ address: tok.address, event: ev, args: { from: d.address }, fromBlock: a, toBlock: b });
+                for (const l of got)
+                    logs.push({ block: l.blockNumber, tx: l.transactionHash, to: String(l.args.to).toLowerCase(), value: l.args.value });
+            }
+            catch (e) {
+                console.log(`[dividends] ${d.name}: chunk ${a}-${b} failed: ${(e.shortMessage || e.message).split('\n')[0]}`);
+                throw e;
+            }
+        }
+        logs.sort((x, y) => (x.block < y.block ? -1 : x.block > y.block ? 1 : 0));
+        // group into drops by block gaps
+        const groups = [];
+        for (const l of logs) {
+            const g = groups[groups.length - 1];
+            if (g && l.block - g[g.length - 1].block <= GAP_BLOCKS)
+                g.push(l);
+            else
+                groups.push([l]);
+        }
+        for (const g of groups) {
+            const first = g[0].block, last = g[g.length - 1].block;
+            const id = `${d.address.slice(2, 10)}-${first}`;
+            if (index.drops.some((x) => x.id === id))
+                continue;
+            const blk = await pub.getBlock({ blockNumber: first });
+            const ts = Number(blk.timestamp);
+            // a payout is a batch: many transfers in one transaction. a transaction that pays one or two wallets is the
+            // distributor moving its own money (a prize, a refund, a top-up), not a dividend, and stays out of the ledger.
+            const perTx = {};
+            for (const l of g)
+                (perTx[l.tx] ??= new Set()).add(l.to);
+            const paid = g.filter((l) => perTx[l.tx].size >= 3);
+            const byTo = {};
+            for (const l of paid) {
+                if (l.value === 0n)
+                    continue;
+                byTo[l.to] = (byTo[l.to] ?? 0n) + l.value;
+            }
+            const recips = Object.entries(byTo).filter(([, v]) => Number(formatUnits(v, tok.decimals)) >= 0.0001);
+            if (recips.length < 3)
+                continue; // three or fewer wallets is a transfer, not a drop
+            const total = recips.reduce((t, [, v]) => t + v, 0n);
+            const totalNum = Number(formatUnits(total, tok.decimals));
+            const price = await priceAt(d.token, ts, priceCache);
+            const drop = { id, distributor: d.address.toLowerCase(), name: d.name, token: tok.address, symbol: d.token, firstBlock: Number(first), lastBlock: Number(last), ts: new Date(ts * 1000).toISOString(), txs: new Set(paid.map((l) => l.tx)).size, recipients: recips.length, total: totalNum.toFixed(6), priceUsd: price, usd: price ? Number((totalNum * price).toFixed(2)) : null };
+            index.drops.push(drop);
+            newDrops++;
+            writeJson(join(dir, 'drops', `${id}.json`), recips.map(([to, v]) => [to, Number(formatUnits(v, tok.decimals)).toFixed(6)]));
+            for (const [to, v] of recips) {
+                const s = loadShard(shardOf(to));
+                (s[to] ??= []).push({ d: id, a: Number(formatUnits(v, tok.decimals)).toFixed(6) });
+            }
+            console.log(`[dividends] ${d.name}: drop ${drop.ts.slice(0, 16)} · ${totalNum.toFixed(2)} ${d.token} to ${recips.length} wallets${price ? ` · about $${(totalNum * price).toFixed(0)}` : ''}`);
+        }
+        state[key] = Number(head);
+    }
+    for (const [s, v] of Object.entries(walletShards))
+        writeJson(join(dir, 'wallets', `${s}.json`), v);
+    index.drops.sort((a, b) => a.ts.localeCompare(b.ts));
+    const cutoff = Date.now() - 30 * 86_400_000;
+    index.distributors = [];
+    for (const d of registry) {
+        const mine = index.drops.filter((x) => x.distributor === d.address.toLowerCase());
+        const uniq = new Set();
+        for (const x of mine) {
+            for (const [to] of readJson(join(dir, 'drops', `${x.id}.json`), []))
+                uniq.add(to);
+        }
+        const usd = mine.reduce((t, x) => t + (x.usd ?? 0), 0);
+        const usd30 = mine.filter((x) => new Date(x.ts).getTime() >= cutoff).reduce((t, x) => t + (x.usd ?? 0), 0);
+        const cap = await marketCap(d.memeToken);
+        index.distributors.push({ ...d, drops: mine.length, total: mine.reduce((t, x) => t + Number(x.total), 0).toFixed(4), usd: Number(usd.toFixed(2)), recipients: uniq.size, last: mine.at(-1)?.ts ?? null, last30dUsd: Number(usd30.toFixed(2)), marketCapUsd: cap, per100Usd30d: cap ? Number(((usd30 / cap) * 100).toFixed(4)) : null });
+    }
+    // every wallet ever paid, ranked: the leaderboard reads the top of it, a statement finds its own line for a rank
+    const priceOf = {};
+    for (const x of index.drops)
+        priceOf[x.id] = x.priceUsd;
+    const totals = {};
+    const tsOf = {};
+    for (const x of index.drops)
+        tsOf[x.id] = x.ts;
+    const shards = new Set();
+    for (const x of index.drops)
+        for (const [to] of readJson(join(dir, 'drops', `${x.id}.json`), []))
+            shards.add(shardOf(to));
+    for (const sh of shards) {
+        for (const [w, rows] of Object.entries(loadShard(sh))) {
+            for (const r of rows) {
+                const t = (totals[w] ??= { gme: 0, usd: 0, drops: 0, first: tsOf[r.d] ?? '', last: '' });
+                t.gme += Number(r.a);
+                t.usd += priceOf[r.d] ? Number(r.a) * priceOf[r.d] : 0;
+                t.drops++;
+                const ts = tsOf[r.d] ?? '';
+                if (ts && (!t.first || ts < t.first))
+                    t.first = ts;
+                if (ts > t.last)
+                    t.last = ts;
+            }
+        }
+    }
+    // in a row: counting back from each distributor's newest drop, how many paid this wallet without a miss
+    const paidIn = {};
+    for (const sh of shards)
+        for (const [w, rows] of Object.entries(loadShard(sh)))
+            paidIn[w] = new Set(rows.map((r) => r.d));
+    // a round is a distributor's drops on one utc day; paid in any drop of the day counts as paid in the round
+    const rounds = {};
+    for (const x of index.drops) {
+        const r = (rounds[x.distributor] ??= []);
+        const day = x.ts.slice(0, 10);
+        const last = r[r.length - 1];
+        if (last && last.day === day)
+            last.push(x.id);
+        else {
+            const g = [x.id];
+            g.day = day;
+            r.push(g);
+        }
+    }
+    const streakOf = (w) => Math.max(0, ...Object.values(rounds).map((rs) => { let n = 0; for (let i = rs.length - 1; i >= 0; i--) {
+        if (rs[i].some((id) => paidIn[w]?.has(id)))
+            n++;
+        else
+            break;
+    } return n; }));
+    const holders = Object.entries(totals).sort((a, b) => b[1].usd - a[1].usd || b[1].gme - a[1].gme).map(([w, t]) => [w, t.gme.toFixed(6), Number(t.usd.toFixed(2)), t.drops, t.first.slice(0, 10), t.last.slice(0, 10), streakOf(w)]);
+    writeJson(join(dir, 'holders.json'), { updatedAt: new Date().toISOString(), count: holders.length, rows: holders });
+    // the page loads the top of the book and a wallet's rank from small shards; the full ranking only on request
+    writeJson(join(dir, 'top.json'), { updatedAt: new Date().toISOString(), count: holders.length, rows: holders.slice(0, 500) });
+    mkdirSync(join(dir, 'ranks'), { recursive: true });
+    const rankShards = {};
+    holders.forEach((r, i) => { (rankShards[shardOf(String(r[0]))] ??= {})[String(r[0])] = i + 1; });
+    for (const [sh, m] of Object.entries(rankShards))
+        writeJson(join(dir, 'ranks', `${sh}.json`), m);
+    // and one ranked book per distributor, so a token's own page ranks its own holders
+    for (const d of registry) {
+        const dl = d.address.toLowerCase();
+        const mine = new Set(index.drops.filter((x) => x.distributor === dl).map((x) => x.id));
+        if (!mine.size)
+            continue;
+        const per = {};
+        for (const sh of shards)
+            for (const [w, rows] of Object.entries(loadShard(sh)))
+                for (const r of rows) {
+                    if (!mine.has(r.d))
+                        continue;
+                    const t = (per[w] ??= { gme: 0, usd: 0, drops: 0, first: '', last: '' });
+                    t.gme += Number(r.a);
+                    t.usd += priceOf[r.d] ? Number(r.a) * priceOf[r.d] : 0;
+                    t.drops++;
+                    const ts = tsOf[r.d] ?? '';
+                    if (ts && (!t.first || ts < t.first))
+                        t.first = ts;
+                    if (ts > t.last)
+                        t.last = ts;
+                }
+        const rs = rounds[dl] ?? [];
+        const streak = (w) => { let n = 0; for (let i = rs.length - 1; i >= 0; i--) {
+            if (rs[i].some((id) => paidIn[w]?.has(id)))
+                n++;
+            else
+                break;
+        } return n; };
+        const rows = Object.entries(per).sort((a, b) => b[1].usd - a[1].usd || b[1].gme - a[1].gme).map(([w, t]) => [w, t.gme.toFixed(6), Number(t.usd.toFixed(2)), t.drops, t.first.slice(0, 10), t.last.slice(0, 10), streak(w)]);
+        writeJson(join(dir, `holders-${dl.slice(2, 10)}.json`), { updatedAt: new Date().toISOString(), distributor: dl, count: rows.length, rows });
+    }
+    index.distributors.sort((a, b) => b.usd - a.usd);
+    index.tokens = TOKENS;
+    index.updatedAt = new Date().toISOString();
+    writeJson(join(dir, 'index.json'), index);
+    writeJson(join(dir, 'state.json'), state);
+    console.log(`[dividends] ${index.drops.length} drops from ${registry.length} distributor(s), ${newDrops} new, through block ${head}`);
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clockwork-press",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clockwork-press",
-      "version": "0.2.0",
+      "version": "0.2.3",
       "license": "SEE LICENSE IN LICENSE",
       "dependencies": {
         "viem": "2.56.3"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clockwork-press",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "description": "your fees, on a clock, with receipts. ClockWorks, the fee machine for tokens on robinhood chain.",

package/skills/clockwork/SKILL.md

@@ -32,7 +32,7 @@ Docs: https://gmerald.xyz/clockwork/docs/
 
 ## The steps
 1. **Write the config.** In a terminal with Node 20 or newer, in an empty folder:
-   `npx --yes clockwork-press@0.2.1 init <token address>`
+   `npx --yes clockwork-press@0.2.2 init <token address>`
    It reads the launch from the pons factory and writes `clockwork.json`. Fill `wallets.machine`,
    `wallets.treasury`, the `split`, and `slices.rule` (`{ "kind": "pace", "pace": "steady" }`). If they want
    Telegram, set `telegram.mode` to `own` and `telegram.chatId` to their group id. Do not put a key or a token
@@ -48,12 +48,14 @@ Docs: https://gmerald.xyz/clockwork/docs/
    the float, and `dry: would swap …`. The machine refuses to run if the key belongs to a different wallet
    than `wallets.machine`; that is the guard working, not a bug.
 5. **Point the fees at the machine.** First claim what is already owed to the current recipient
-   (`npx --yes clockwork-press@0.2.1 claimcheck` from the folder with `clockwork.json` prints it), because a
+   (`npx --yes clockwork-press@0.2.2 claimcheck` from the folder with `clockwork.json` prints it), because a
    recipient change does not move credited balances. Then the current recipient signs
    `transferCreatorFeeRecipient(token, machineWallet)` on the pons factory
    `0x7eD598BcEf8bd9Edd8C97A195C6d13f40801EC7e`. Prepare the calldata for them (function selector
    `0x2931861b`, then the token address and the machine address each left-padded to 32 bytes) and tell them
-   to send it as a raw transaction from that wallet with value 0. The pons UI does not show this function;
+   to send it as a raw transaction from that wallet with value 0, or point them at
+   https://gmerald.xyz/clockwork/point/?token=<token>&machine=<machine>, which reads the chain, shows what is
+   owed, and prepares the same transaction for their own wallet. The pons UI does not show this function;
    the contract has it and it takes effect immediately.
 6. **Go live.** Set `claim.mode` to `auto` in `clockwork.json` if it is not already, commit, and let the
    workflow's schedule run it on the quarter hour. Optional: a cron-job.org job that POSTs to
@@ -74,7 +76,7 @@ Docs: https://gmerald.xyz/clockwork/docs/
 
 ## Commands
 `init <token>` write the config from the chain · `dry` a tick without signing · `press` the tick ·
-`claimcheck` what the escrow holds and what is unswept · `doctor` RPC, wallet, gas, recipient, Telegram ·
+`claimcheck` what the escrow holds and what is unswept · `dividends` (0.2.3) reads every payout the listed memestock distributors made to holders into a public book, no key, any folder, `DIVIDENDS_DIR` names where · `doctor` RPC, wallet, gas, recipient, Telegram ·
 `handback <address>` claim what is credited, then move the fee recipient · `holders` the holder count.
 
 ## What ClockWorks costs