clockwork-press 0.2.1 → 0.2.3

package/dist/env.js

@@ -34,7 +34,7 @@ export const cfg = {
     // a native launch is quoted in eth: the pair address is the zero address and the escrow keeps it on its native ledger.
     gme: c.pair.address, pair: c.pair.address, pairSymbol: pairNative ? 'ETH' : c.pair.symbol, pairDecimals: pairNative ? 18 : c.pair.decimals ?? 18, pairNative,
     token: c.token.address, tokenSymbol: c.token.symbol, tokenName: c.token.name, totalSupply: c.token.supply ?? 1_000_000_000,
-    escrow: (c.launch.feeEscrow || ''), locker: (c.launch.locker || ''), claimMode: c.claim.mode, claimFloor: Number(c.claim.floor ?? 5), claimEveryHours: Number(c.claim.atLeastEveryHours ?? 24),
+    escrow: (c.launch.feeEscrow || ''), locker: (c.launch.locker || ''), claimMode: c.claim.mode, claimFloor: Number(c.claim.floor ?? 5), lowGasEth: Number(c.alerts?.lowGasEth ?? 0.005), claimEveryHours: Number(c.claim.atLeastEveryHours ?? 24),
     hook: (c.launch.hook || '0xE5e702641Ea86F4ae6cC3cDaeD2B886f976Be044'), vault: (c.launch.vault || '0x42df2a798f82289E177311362e8f5ccC45c1219c'),
     vestMode: c.buyback?.vest ?? 'burn', paceWord: pace,
     // ops is '' when the client has no ops wallet; the ops leg then holds (and validate() refuses opsBps > 0 without one)

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/dist/jobs/init.js

@@ -56,10 +56,10 @@ export async function runInit() {
         split: house ? { burnBps: 5000, treasuryBps: 5000, opsBps: 0, serviceBps: 0 } : { burnBps: 4500, treasuryBps: 4500, opsBps: 0, serviceBps: 1000 },
         schedule: { cadenceMin: 15, weekends: true, napUntil: null },
         slices: { rule: { kind: 'pace', pace: 'steady' }, dip: { on: false, bandBps: 1000, multiplier: 2 }, quoteSanityBps: 1500, maxSlippageBps: 300 },
-        burn: { method: 'burn' }, buyback: { vest: 'burn' }, claim: { mode: 'auto', floor: pair.symbol === 'ETH' || pair.symbol === 'WETH' ? 0.05 : 5, atLeastEveryHours: 24 },
-        telegram: { mode: 'shared', cards: { claim: true, slice: true, percent: true, buys: false }, buyFloorUsd: 50 },
+        burn: { method: 'burn' }, buyback: { vest: 'burn' }, claim: { mode: 'auto', floor: ['ETH', 'WETH'].includes(String(pair.symbol)) ? 0.05 : ['USDG', 'USDC', 'USDT', 'DAI', 'USD1'].includes(String(pair.symbol).toUpperCase()) ? 100 : 5, atLeastEveryHours: 24 },
+        telegram: { mode: 'own', chatId: '', cards: { claim: true, slice: true, percent: true, buys: false }, buyFloorUsd: 50 }, // own bot until the shared clockwork bot exists; chatId from `clockwork tgcheck`
         site: { enabled: true, modules: ['treasury', 'burns', 'holders', 'seats', 'wallet', 'rank', 'ledger'], seatThreshold: 250000 },
-        brand: { name: tName, treasuryWord: 'treasury', burnWord: 'burn', accent: '#3DFF8E' },
+        brand: { name: tName, treasuryWord: 'treasury', burnWord: 'burn', accent: '#0B6E4F', avatar: '' },
     };
     writeFileSync(out, JSON.stringify(cfg, null, 1) + '\n');
     console.log(`wrote ${out}: ${tName} (${tSym}) paired with ${pair.symbol}${native ? ' (native)' : ` at ${pair.address}`}, ${PHASES[Number(lt.phase)] ?? `phase ${lt.phase}`}, buybacks ${lt.buybackEnabled ? 'on' : 'off'}.`);

package/dist/press.js

@@ -108,6 +108,31 @@ async function scanStash(fairUsd) {
         await postCard(ART.press, [`${cfg.emoji} ${W.claim} #${entry.k}`, `${W.treasury}: +${gme.toFixed(2)} ${cfg.pairSymbol}. never sold, never distributed.`, fedNote ? fedNote.trim() : null, `the ${W.treasury}: ${Math.round(totals().stashedGme).toLocaleString('en-US')} ${cfg.pairSymbol}`]);
         added++;
     }
+    // the treasury-outflow watch: the treasury only grows; any transfer out of it is news, posted once per hash
+    try {
+        const outs = await pub.getLogs({
+            address: cfg.gme, event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
+            args: { from: cfg.stash }, fromBlock: from, toBlock: latest,
+        });
+        for (const log of outs) {
+            const amt = log.args.value;
+            if (amt === 0n)
+                continue;
+            const l = readLedger();
+            l.meta = { ...(l.meta ?? {}) };
+            const seen = l.meta.treasuryOutflows ?? [];
+            if (seen.some((o) => o.tx === log.transactionHash))
+                continue;
+            const rec = { tx: log.transactionHash, amount: Number(formatUnits(amt, cfg.pairDecimals)).toFixed(4), to: String(log.args.to), at: new Date().toISOString() };
+            l.meta.treasuryOutflows = [...seen, rec].slice(-20);
+            writeLedger(l);
+            console.log(`[press] the ${W.treasury} moved: ${rec.amount} ${cfg.pairSymbol} left it to ${rec.to.slice(0, 6)}…${rec.to.slice(-4)} (${rec.tx})`);
+            await postCard('', [`${cfg.emoji} the ${W.treasury} moved`, `${rec.amount} ${cfg.pairSymbol} left the ${W.treasury} to ${rec.to.slice(0, 6)}…${rec.to.slice(-4)}.`, `if this was the founder, nothing to do. if not, look now.`]);
+        }
+    }
+    catch (e) {
+        console.log(`[press] outflow watch skipped: ${e.shortMessage || e.message}`);
+    }
     const l2 = readLedger();
     l2.stashScanBlock = latest.toString();
     writeLedger(l2);
@@ -303,8 +328,12 @@ async function pressOnce(runAt, commit) {
     // what every stats write carries this run; the recipient watch and unswept are filled in once known.
     // the recipient row is red whenever an auto-mode machine is not where the fees point, key or no key.
     // lastRunAt is whatever the file holds: markRun sets it when a run commits to work, never a napping tick.
+    // supply locked at graduation sits in the pons locker and never comes out: out of circulation, like a burn
+    const lockedTokens = cfg.locker ? await tryRead('locker', () => pub.readContract({ address: token, abi: erc20Abi, functionName: 'balanceOf', args: [cfg.locker] }), 0n) : 0n;
+    const locked = lockedTokens > 0n ? { tokens: formatUnits(lockedTokens, 18), pctOfMint: ((Number(lockedTokens) / Number(TOTAL_SUPPLY)) * 100).toFixed(2) } : null;
     const common = () => ({
         presses: countKind('press'), snacks: countKind('snack'), checkedAt: new Date().toISOString(), peg: pegOut,
+        locked, treasuryOutflow: readLedger().meta?.treasuryOutflows?.at(-1) ?? null,
         cadenceMin: cfg.cadenceMin, days: dailyRollup(), holders, lastRunAt: prevStats().lastRunAt,
         phase: s.phaseWord, graduationPct: s.graduationPct,
         feeRecipient: { address: s.recipient, ok: cfg.claimMode !== 'auto' || same(s.recipient, cfg.pressWallet) }, pendingRecipient: null,
@@ -327,6 +356,26 @@ async function pressOnce(runAt, commit) {
     }
     const me = account().address;
     const w = wallet();
+    // one card a day when the machine wallet runs low on gas; the number rides in stats for the status page
+    let gasEth = '0', gasLow = false;
+    try {
+        const gas = await pub.getBalance({ address: me });
+        gasEth = Number(formatUnits(gas, 18)).toFixed(4);
+        gasLow = gas < parseUnits(String(cfg.lowGasEth), 18);
+        if (gasLow) {
+            const l = readLedger();
+            const last = l.meta?.lowGasAlertAt ? new Date(l.meta.lowGasAlertAt).getTime() : 0;
+            console.log(`[press] gas low: ${gasEth} eth in the machine wallet (floor ${cfg.lowGasEth})`);
+            if (Date.now() - last > 86_400_000 && !cfg.dry) {
+                l.meta = { ...(l.meta ?? {}), lowGasAlertAt: new Date().toISOString() };
+                writeLedger(l);
+                await postCard('', [`${cfg.emoji} gas is low`, `the machine wallet holds ${gasEth} eth. a few more ticks and it cannot burn.`, `send a little eth to ${me.slice(0, 6)}…${me.slice(-4)}.`]);
+            }
+        }
+    }
+    catch (e) {
+        console.log(`[press] gas check skipped: ${e.shortMessage || e.message}`);
+    }
     // 0b. The recipient watch, then the claim block.
     const watch = await watchRecipient(s, me);
     const mine = same(s.recipient, me);
@@ -425,7 +474,7 @@ async function pressOnce(runAt, commit) {
             }
         }
     }
-    const watched = () => ({ ...common(), feeRecipient: watch.feeRecipient, pendingRecipient: watch.pendingRecipient, unswept: unsweptOut, escrowOwed: escrowOut, claimFloor: cfg.claimFloor });
+    const watched = () => ({ ...common(), feeRecipient: watch.feeRecipient, pendingRecipient: watch.pendingRecipient, unswept: unsweptOut, escrowOwed: escrowOut, claimFloor: cfg.claimFloor, gasEth, gasLow });
     // 2. The float. Everything the wallet holds is pressed; held-back ops
     //    slices from earlier presses roll in naturally. A native pair keeps its gas money.
     let floatBal = await pairBal(me);

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,9 +1,9 @@
 {
   "name": "clockwork-press",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
-  "description": "your fees, on a clock, with receipts. the fee machine for tokens on robinhood chain.",
+  "description": "your fees, on a clock, with receipts. ClockWorks, the fee machine for tokens on robinhood chain.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",

package/skills/clockwork/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: clockwork
-description: Set up and run a Clockwork machine for a pons v2 token on Robinhood Chain. Use when a founder asks to automate their creator fees, buy back and burn, build a treasury, or "run Clockwork" for their token. Walks the human through the machine wallet, the config, the repository, the secrets, the dry run, pointing fees at the machine, and going live. Never touches a private key.
+description: Set up and run a ClockWorks machine for a pons v2 token on Robinhood Chain. Use when a founder asks to automate their creator fees, buy back and burn, build a treasury, or "run ClockWorks" for their token. Walks the human through the machine wallet, the config, the repository, the secrets, the dry run, pointing fees at the machine, and going live. Never touches a private key.
 ---
 
-# Clockwork, with an assistant next to you
+# ClockWorks, with an assistant next to you
 
-Clockwork runs a token's creator fees on a clock: claims from the pons fee escrow, splits by percentages the
+ClockWorks runs a token's creator fees on a clock: claims from the pons fee escrow, splits by percentages the
 founder sets once, buys the token back and burns it in slices, sends the treasury share to a wallet that only
 grows, and prints every hash. It runs in the founder's own GitHub repository on a wallet the founder created.
 Docs: https://gmerald.xyz/clockwork/docs/
@@ -23,15 +23,16 @@ Docs: https://gmerald.xyz/clockwork/docs/
 1. The token address (a pons v2 launch on Robinhood Chain, chain id 4663).
 2. A fresh machine wallet address, created on their device, with about 0.02 ETH on Robinhood Chain.
 3. A treasury wallet address (a cold wallet is best).
-4. The split they want. Default: 45 burn / 45 treasury / 0 ops / 10 Clockwork. The Clockwork share is at
+4. The split they want. Default: 45 burn / 45 treasury / 0 ops / 10 ClockWorks. The ClockWorks share is at
    least 10 and is what pays for the software.
 5. The pace: gentle (a claim over a day), steady (over six hours, the default), or once (one slice).
-6. Telegram: their own bot token set as a secret (they create the bot in @BotFather), or off for now.
-7. How often to claim: `claim.floor` is how much of the pairing asset must be waiting in the escrow before the machine claims (default 5), and `claim.atLeastEveryHours` claims whatever waits at least that often (default 24). A claim costs gas and posts a card; most machines keep the defaults.
+6. Telegram: their own bot token set as a secret (they create the bot in @BotFather) and the group's chat id from `clockwork tgcheck`, or `telegram.mode` set to `off` for now. The config defaults to `own`; with no token set, the machine logs and posts nothing.
+7. The brand: `brand.name`, the words for treasury and burn (`brand.treasuryWord`, `brand.burnWord`, `brand.claimWord`), `brand.avatar` (an image URL the status page and the wallet card use), and `brand.art` (one image or short mp4 URL per Telegram card).
+8. How often to claim: `claim.floor` is how much of the pairing asset must be waiting in the escrow before the machine claims (default 5), and `claim.atLeastEveryHours` claims whatever waits at least that often (default 24). A claim costs gas and posts a card; most machines keep the defaults.
 
 ## The steps
 1. **Write the config.** In a terminal with Node 20 or newer, in an empty folder:
-   `npx --yes clockwork-press@0.2.0 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
@@ -47,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.0 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
@@ -73,9 +76,9 @@ 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 Clockwork costs
-Ten percent of every claim, sent on chain by the machine, slice by slice, to the Clockwork wallet pinned in
+## What ClockWorks costs
+Ten percent of every claim, sent on chain by the machine, slice by slice, to the ClockWorks wallet pinned in
 the package (`0x6EA62Bd07FE08C7491543d495B42F6dA7ad298D0`). No setup fee. The chain is the invoice.