clockwork-press 0.0.1 → 0.2.1

package/README.md

@@ -1,8 +1,20 @@
-# clockwork-press
+# clockwork
 
 your fees, on a clock, with receipts.
 
-the fee machine for tokens on robinhood chain: it claims a token's creator fees, splits them, burns in slices on a
-fifteen-minute clock, and prints every hash. it runs in your own repository on your own wallet. it never holds a key.
+the fee machine for tokens on robinhood chain: claims, splits, burns, a treasury that only grows, telegram cards,
+a status page, holder tools. no custody: the machine runs in your own repo on your own wallet; every move is a hash.
 
-this version only reserves the name. the first working release ships with client zero, gmerald.xyz.
+- `packages/press` · the machine, published as `clockwork-press` on npm
+- `template` · what a client repo holds: `clockwork.json` and one workflow
+- `docs/PLAN.md` · the plan
+
+status: week one. the press from gmerald.xyz is being generalized here, one decision at a time.
+
+this week, after a reread of the pons v2 docs: the machine sweeps before it claims (fees sit on the curve or the
+hook until a sweep, so an escrow balance of zero never meant nothing was owed) and claims from both escrow
+ledgers, native and per-token, so eth pairs and released buyback vests work. it reads the creator fee recipient and
+any pending takeover every run and says so when fees point somewhere else. the six trading knobs fold into one
+control, the pace: gentle, steady or once; the raw rules stay under advanced. there is one default split
+everywhere, 45 / 45 / 0 / 10, the ops wallet is optional, and the service wallet lives in the package, not in
+any client's file.

package/bin/clockwork.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// clockwork <init|press|dry|doctor|claimcheck|launchcheck|handback <address>|holders|tgcheck|log|buys|quotecheck>
+// (reads clockwork.json from the working directory, or the file CLOCKWORK_CONFIG names)
+// runs the built machine in dist/, plain node, no tsx at runtime: a client's clock executes exactly the
+// javascript that was published, and the package carries no compiler.
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const entry = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'index.js');
+if (!existsSync(entry)) { console.error('clockwork: dist/index.js is missing. build first: npm run build'); process.exit(1); }
+// index.js reads the job from process.argv[2], which is already in place when node runs this file directly
+await import(pathToFileURL(entry).href);

package/dist/abis.js

@@ -0,0 +1,73 @@
+import { parseAbi } from 'viem';
+export const erc20Abi = parseAbi([
+    'function balanceOf(address) view returns (uint256)',
+    'function totalSupply() view returns (uint256)',
+    'function decimals() view returns (uint8)',
+    'function symbol() view returns (string)',
+    'function approve(address spender, uint256 amount) returns (bool)',
+    'function transfer(address to, uint256 amount) returns (bool)',
+    'function burn(uint256 amount)',
+]);
+// the recipient functions live on the factory, which owns the LaunchedToken record. verified on chain
+// 2026-09-06 against gmerald (0x3E4E…9458): pendingCreatorFeeRecipient(token) returns (0x0, 0, 0) from the
+// factory and reverts with empty data on the hook and the escrow; transferCreatorFeeRecipient(token, 0xdead)
+// simulated from a made-up account reverts NotCreatorFeeRecipient (0xb9f93944) on the factory only.
+export const factoryAbi = parseAbi([
+    'struct LaunchedToken { address token; address curve; address deployer; address creatorFeeRecipient; address pairToken; uint256 graduationThreshold; uint24 poolFee; int24 tickSpacing; uint16 creatorTaxBps; bool buybackEnabled; uint8 phase; uint256 sweptQuote; uint256 sweptTokens; uint256 sweptAt; bool exists; }',
+    'function getLaunchedToken(address token) view returns (LaunchedToken)',
+    'function approvedPairTokens(address pairToken) view returns (bool)',
+    'function pairTokenEconomics(address pairToken) view returns (uint256 phantomQuote, uint256 graduationThreshold, uint8 decimals)',
+    'function pendingCreatorFeeRecipient(address token) view returns (address to, uint256 effectiveAt, uint256 expiresAt)',
+    'function transferCreatorFeeRecipient(address token, address newRecipient)',
+    'error NotCreatorFeeRecipient()',
+    'error TimelockNotElapsed()',
+    'error TimelockExpired()',
+]);
+export const curveAbi = parseAbi([
+    'function getReserves() view returns (uint256 quoteReserve, uint256 tokenReserve)',
+    'function sellableTokens() view returns (uint256)',
+    'function readyToGraduate() view returns (bool)',
+    'function feeBps() view returns (uint256)',
+    'function creatorTaxBps() view returns (uint256)',
+    'function currentSnipeTaxBps(address recipient) view returns (uint256)',
+    'function quoteFeeBalance() view returns (uint256)',
+    'function creatorTaxBalance() view returns (uint256)',
+    'function buy(uint256 quoteIn, uint256 minTokensOut, address recipient) payable returns (uint256 tokensOut)',
+    'function realQuoteReserve() view returns (uint256)',
+    'function graduationThreshold() view returns (uint256)',
+    'function sweepFees(uint256 minBuybackTokensOut)',
+    'error InternalSwapRequiresOperator()',
+    'error CurveGraduated()',
+]);
+// the meme hook: fees accrue here per pool and per currency after graduation, until a sweep moves them.
+// poolId is the uniswap v4 key hash (see poolIdFor in pons.ts). a creator's sweepPoolFees reverts
+// InternalSwapRequiresOperator (0x31cdb504, seen live) whenever launch-token fees need converting.
+export const hookAbi = parseAbi([
+    'function pendingFees(bytes32 poolId, address currency) view returns (uint256)',
+    'function pendingCreatorTax(bytes32 poolId, address currency) view returns (uint256)',
+    'function sweepPoolFees(bytes32 poolId, uint256 minConversionQuoteOut, uint256 minBuybackTokensOut)',
+    'error InternalSwapRequiresOperator()',
+]);
+// two ledgers: native (balanceOf / claim) for eth-quoted launches, per-token (balanceOfToken / claimToken)
+// for custom pairs. a released buyback vest credits the per-token ledger under the launch token itself.
+export const escrowAbi = parseAbi([
+    'function balanceOf(address recipient) view returns (uint256)',
+    'function balanceOfToken(address recipient, address token) view returns (uint256)',
+    'function claim()',
+    'function claimToken(address token)',
+]);
+// the buyback vault: bought-back supply vesting over five years from a weighted start.
+export const vaultAbi = parseAbi([
+    'function releasable(address token) view returns (uint256)',
+    'function release(address token) returns (uint256 released)',
+    'function totalLocked(address token) view returns (uint256)',
+    'function totalReleased(address token) view returns (uint256)',
+    'function vestedAmount(address token) view returns (uint256)',
+    'function vestingStart(address token) view returns (uint256)',
+    'function VESTING_DURATION() view returns (uint256)',
+    'error NotVestBeneficiary()',
+]);
+export const feedAbi = parseAbi([
+    'function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)',
+    'function decimals() view returns (uint8)',
+]);

package/dist/chain.js

@@ -0,0 +1,24 @@
+import { createPublicClient, createWalletClient, defineChain, fallback, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { cfg } from './env.js';
+export const robinhood = defineChain({
+    id: 4663,
+    name: 'Robinhood Chain',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    rpcUrls: { default: { http: [cfg.rpcUrl] } },
+});
+// the public rpc rate-limits shared runners ("Too Many Requests"): back off and retry for a couple of minutes
+// before giving up, and use a second rpc if one is configured (RPC_URL_2).
+const opts = { retryCount: 6, retryDelay: 1500, timeout: 20_000 };
+const transport = () => (cfg.rpcUrl2 ? fallback([http(cfg.rpcUrl, opts), http(cfg.rpcUrl2, opts)]) : http(cfg.rpcUrl, opts));
+export const pub = createPublicClient({ chain: robinhood, transport: transport() });
+export const account = () => {
+    if (!cfg.key)
+        throw new Error('MACHINE_WALLET_KEY not set');
+    const k = cfg.key.startsWith('0x') ? cfg.key : `0x${cfg.key}`;
+    const a = privateKeyToAccount(k);
+    if (a.address.toLowerCase() !== String(cfg.pressWallet).toLowerCase())
+        throw new Error(`the key is for ${a.address}, but clockwork.json names ${cfg.pressWallet} as the machine wallet; refusing to run`);
+    return a;
+};
+export const wallet = () => createWalletClient({ account: account(), chain: robinhood, transport: transport() });

package/dist/config.js

@@ -0,0 +1,62 @@
+export const SERVICE_MIN_BPS = 1000;
+export const ZERO = '0x0000000000000000000000000000000000000000';
+// the clockwork wallet. pinned here, in the package, not in any client's config: the founder creates it and it is set once.
+export const CLOCKWORK_ADDRESS = '0x6EA62Bd07FE08C7491543d495B42F6dA7ad298D0'; // the founder's service wallet, created 2026-09-06; a plain wallet, never a contract
+// the house does not pay itself. detected by token, so no client file can claim the exemption by naming an address.
+export const HOUSE_TOKENS = ['0x3e4e7bbee9a7e5fbedabeea66313c8f636999458'];
+export const isHouse = (token) => HOUSE_TOKENS.includes(String(token).toLowerCase());
+const isAddr = (a) => /^0x[0-9a-fA-F]{40}$/.test(String(a ?? ''));
+const isZero = (a) => /^0x0{40}$/i.test(String(a ?? ''));
+export function validate(c) {
+    const bad = (m) => { throw new Error(`clockwork.json: ${m}`); };
+    if (c?.version !== 1)
+        bad('version must be 1');
+    for (const k of ['token', 'pair', 'launch', 'wallets', 'split', 'schedule', 'slices', 'burn', 'claim', 'telegram', 'site', 'brand'])
+        if (!c[k])
+            bad(`missing "${k}"`);
+    if (!isAddr(c.token.address) || isZero(c.token.address))
+        bad('token.address is not an address');
+    const s = c.split;
+    if (s.burnBps + s.treasuryBps + s.opsBps + s.serviceBps !== 10000)
+        bad('split must sum to 10000 bps');
+    if (s.serviceBps < SERVICE_MIN_BPS && !isHouse(c.token.address))
+        bad(`serviceBps must be at least ${SERVICE_MIN_BPS}`);
+    // a paying client's run would transfer to 0x0 and revert after the burn and the treasury legs: refuse before the first tick
+    if (s.serviceBps > 0 && CLOCKWORK_ADDRESS === ZERO)
+        bad('the service wallet is not pinned in this build of clockwork-press; update the package');
+    // the zero address is a valid-looking hex string that destroys a native pair and reverts an erc20 transfer
+    // after the buy leg has landed; a template left half-filled fails here, never on chain.
+    for (const w of ['machine', 'treasury']) {
+        if (!isAddr(c.wallets[w]))
+            bad(`wallets.${w} is not an address`);
+        if (isZero(c.wallets[w]))
+            bad(`wallets.${w} is the zero address; fill it in`);
+    }
+    if (String(c.wallets.machine).toLowerCase() === String(c.wallets.treasury).toLowerCase())
+        bad('wallets.treasury must not be the machine wallet (the machine burns what it holds)');
+    if (s.opsBps > 0 && !isAddr(c.wallets.ops))
+        bad('wallets.ops is needed when split.opsBps is above zero');
+    if (c.wallets.ops !== undefined && (!isAddr(c.wallets.ops) || isZero(c.wallets.ops)))
+        bad('wallets.ops is not an address');
+    if (c.pair.native) {
+        if (!/^0x0{40}$/i.test(String(c.pair.address)))
+            bad('pair.native launches use the zero address');
+    }
+    else if (!isAddr(c.pair.address))
+        bad('pair.address is not an address');
+    const r = c.slices.rule;
+    if (!r?.kind)
+        bad('slices.rule needs a kind');
+    if (r.kind === 'pace' && !['gentle', 'steady', 'once'].includes(r.pace))
+        bad('slices.rule.pace must be gentle, steady or once');
+    if (c.buyback && !['burn', 'hold'].includes(c.buyback.vest))
+        bad('buyback.vest must be burn or hold');
+    if (![5, 15, 30, 60].includes(c.schedule.cadenceMin))
+        bad('schedule.cadenceMin must be 5, 15, 30 or 60');
+    if (c.claim.floor != null && !(Number(c.claim.floor) >= 0))
+        bad('claim.floor must be a number of the pairing asset, 0 or more');
+    if (c.claim.atLeastEveryHours != null && !(Number(c.claim.atLeastEveryHours) >= 1))
+        bad('claim.atLeastEveryHours must be 1 or more');
+    if (c.launch.kind === 'pons-v2' && !(c.launch.feeEscrow && c.launch.factory))
+        bad('pons-v2 launches need launch.factory and launch.feeEscrow');
+}

package/dist/env.js

@@ -0,0 +1,86 @@
+// clockwork.json is the machine's configuration and the client owns it. The only secret is the machine
+// wallet's key (MACHINE_WALLET_KEY). Everything the press used to read from environment variables comes
+// from the file, mapped onto the same names, so the machine's code stays the code that ran gmerald.xyz.
+import { readFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { validate, isHouse, SERVICE_MIN_BPS, CLOCKWORK_ADDRESS } from './config.js';
+const configPath = resolve(process.env.CLOCKWORK_CONFIG || 'clockwork.json');
+let c;
+try {
+    c = JSON.parse(readFileSync(configPath, 'utf8'));
+}
+catch (e) {
+    throw new Error(`cannot read ${configPath}: ${e.message}`);
+}
+validate(c);
+const opt = (k, d = '') => { const v = process.env[k]; return v === undefined || v === '' ? d : v; };
+const rule = c.slices.rule;
+const dataDir = resolve(dirname(configPath), c.data?.dir || 'data');
+mkdirSync(dataDir, { recursive: true });
+const house = isHouse(c.token.address);
+// the pace rule is the wizard's one control; it maps onto the raw rules the press already knows how to run.
+// gentle spreads a claim over a day, steady over six hours, once eats the float in one slice.
+const pace = rule.kind === 'pace' ? rule.pace : 'custom';
+const spreadHours = rule.kind === 'spread' ? rule.hours : pace === 'gentle' ? 24 : pace === 'steady' ? 6 : 0;
+const fractionBps = rule.kind === 'fraction' ? rule.bps : rule.kind === 'oneclip' || pace === 'once' ? 10000 : 1667;
+const pairNative = !!c.pair.native;
+export const cfg = {
+    configPath, configDir: dirname(configPath),
+    rpcUrl: c.chain.rpc || 'https://rpc.mainnet.chain.robinhood.com',
+    rpcUrl2: c.chain.rpc2 || opt('RPC_URL_2'),
+    explorer: c.chain.explorer || 'https://robinhoodchain.blockscout.com',
+    factory: (c.launch.factory || '0x7eD598BcEf8bd9Edd8C97A195C6d13f40801EC7e'),
+    // the pairing asset. the machine's code still calls it "gme" in places; it is whatever the launch is priced in.
+    // 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),
+    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)
+    stash: c.wallets.treasury, ops: c.wallets.ops || '', pressWallet: c.wallets.machine, service: CLOCKWORK_ADDRESS, house,
+    key: opt('MACHINE_WALLET_KEY', opt('PRESS_WALLET_KEY')),
+    dry: opt('CLOCKWORK_DRY_RUN') === '1' || opt('PRESS_DRY_RUN') === '1',
+    slippageBps: BigInt(c.slices.maxSlippageBps ?? 300), minPressGme: String(c.slices.minSlice ?? 0.05),
+    burnBps: BigInt(c.split.burnBps), stashBps: BigInt(c.split.treasuryBps), opsBps: BigInt(c.split.opsBps),
+    serviceBps: BigInt(house ? c.split.serviceBps : Math.max(c.split.serviceBps, SERVICE_MIN_BPS)), BPS: 10000n,
+    pegFeed: (c.pair.usdFeed || ''), pegToleranceBps: 0, opsForce: false, v4SwapEnabled: true,
+    pressFractionBps: BigInt(fractionBps),
+    pressSliceGme: rule.kind === 'fixed' ? String(rule.amount) : '0',
+    pressSliceUsd: rule.kind === 'usd' ? rule.floorUsd : 0,
+    pressSpreadHours: spreadHours,
+    napUntil: c.schedule.napUntil || '', quietHours: c.schedule.quietHoursUtc, weekends: c.schedule.weekends ?? true,
+    dipMode: !!c.slices.dip?.on, dipBandBps: c.slices.dip?.bandBps ?? 1000, dipMultiplier: BigInt(Math.max(1, Math.round(c.slices.dip?.multiplier ?? 2))),
+    quoteSanityBps: c.slices.quoteSanityBps ?? 1500, cadenceMin: c.schedule.cadenceMin, refreshMin: 55,
+    minBuyUsd: String(c.telegram.buyFloorUsd ?? 50), buyStepUsd: '100',
+    tgToken: c.telegram.mode === 'off' ? '' : opt('TELEGRAM_BOT_TOKEN'), tgChat: c.telegram.chatId || opt('TELEGRAM_CHAT_ID'), tgMode: c.telegram.mode, cards: c.telegram.cards,
+    gradSeedGme: '0', siteDir: dataDir,
+    words: { claim: c.brand.claimWord || 'claim', slice: c.brand.burnWord || 'burn', treasury: c.brand.treasuryWord || 'treasury' },
+    brandName: c.brand.name, emoji: c.brand.emoji || '⚙️', siteUrl: c.site.url || '', art: c.brand.art || {}, seatThreshold: c.site.seatThreshold ?? 250000,
+};
+export const launched = () => true;
+// A nap: a one-off nap until a time, quiet hours, or weekends off. The claim scanner still runs.
+export function napping() {
+    const now = new Date();
+    if (cfg.napUntil && now.getTime() < new Date(cfg.napUntil).getTime())
+        return { yes: true, until: cfg.napUntil };
+    const d = now.getUTCDay();
+    if (!cfg.weekends && (d === 0 || d === 6)) {
+        const m = new Date(now);
+        m.setUTCDate(m.getUTCDate() + (d === 6 ? 2 : 1));
+        m.setUTCHours(0, 0, 0, 0);
+        return { yes: true, until: m.toISOString() };
+    }
+    if (cfg.quietHours) {
+        const [a, b] = cfg.quietHours, h = now.getUTCHours();
+        const inside = a <= b ? h >= a && h < b : h >= a || h < b;
+        if (inside) {
+            const u = new Date(now);
+            if (h >= b)
+                u.setUTCDate(u.getUTCDate() + 1);
+            u.setUTCHours(b, 0, 0, 0);
+            return { yes: true, until: u.toISOString() };
+        }
+    }
+    return { yes: false, until: '' };
+}

package/dist/gmerank.js

@@ -0,0 +1,85 @@
+// Where the stash ranks among holders of tokenized gme. The explorer blocks automated reads, so the
+// bot keeps its own watch list: the explorer's top 50 (seeded by hand) plus any wallet that receives
+// 200 gme or more in one transfer. Every hour it reads every watched balance and counts how many
+// wallets hold more than the stash. Pools and protocol contracts are not wallets: a contract with a
+// protocol name, or an unnamed contract with real code (over 300 bytes), is left out. Smart wallets
+// (7702 delegations, safes, small proxies) count as holders.
+import { parseAbiItem, formatUnits } from 'viem';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cfg } from './env.js';
+import { pub } from './chain.js';
+const path = () => join(cfg.siteDir, 'gme-rank.json');
+const PROTOCOL = /pool|manager|locker|hook|initializer|escrow|curve|core|reflections|router|permit|bridge|vault|dividend|factory|quoter|position/i;
+const BIG_TRANSFER = 200; // gme
+const FORGET_UNDER = 100; // gme: a watched wallet under this cannot be above the stash; drop it
+export function readRank() {
+    try {
+        const st = JSON.parse(readFileSync(path(), 'utf8'));
+        return st.rank && st.at ? { rank: st.rank, of: st.of ?? 0, at: st.at } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function gmeRank() {
+    let st;
+    try {
+        st = JSON.parse(readFileSync(path(), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (st.at && Date.now() - new Date(st.at).getTime() < 55 * 60_000)
+        return readRank();
+    const stashAddr = String(cfg.stash).toLowerCase();
+    st.watch[stashAddr] ??= { name: 'the stash' };
+    const latest = await pub.getBlockNumber();
+    const ev = parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)');
+    let from = st.lastBlock ? BigInt(st.lastBlock) + 1n : latest - 40000n, step = 10000n, calls = 0;
+    while (from <= latest && calls < 400) {
+        const to = from + step - 1n > latest ? latest : from + step - 1n;
+        try {
+            const logs = await pub.getLogs({ address: cfg.gme, event: ev, fromBlock: from, toBlock: to });
+            calls++;
+            for (const l of logs) {
+                const t = l.args.to.toLowerCase();
+                if (Number(formatUnits(l.args.value, 18)) >= BIG_TRANSFER && !st.watch[t])
+                    st.watch[t] = {};
+            }
+            from = to + 1n;
+            st.lastBlock = to.toString();
+        }
+        catch (e) {
+            calls++;
+            if (step > 500n) {
+                step /= 2n;
+                continue;
+            }
+            console.log(`[gme-rank] scan stopped at ${st.lastBlock}: ${e.shortMessage || e.message}`);
+            break;
+        }
+    }
+    const abi = [parseAbiItem('function balanceOf(address) view returns (uint256)')];
+    for (const [a, w] of Object.entries(st.watch)) {
+        w.gme = Number(formatUnits(await pub.readContract({ address: cfg.gme, abi, functionName: 'balanceOf', args: [a] }), 18));
+        if (w.code == null) {
+            const c = await pub.getCode({ address: a });
+            w.code = c ? (c.length - 2) / 2 : 0;
+        }
+        w.out = a !== stashAddr && ((!!w.name && PROTOCOL.test(w.name)) || (!w.name && (w.code ?? 0) > 300));
+    }
+    const stash = st.watch[stashAddr].gme ?? 0;
+    const holders = Object.entries(st.watch).filter(([, w]) => !w.out && (w.gme ?? 0) > 0);
+    const above = holders.filter(([a, w]) => a !== stashAddr && (w.gme ?? 0) > stash).sort((x, y) => (y[1].gme ?? 0) - (x[1].gme ?? 0));
+    st.rank = above.length + 1;
+    st.of = holders.length;
+    st.at = new Date().toISOString();
+    st.above = above.map(([a, w]) => ({ address: a, gme: Math.round(w.gme ?? 0), name: w.name || undefined }));
+    for (const [a, w] of Object.entries(st.watch))
+        if (a !== stashAddr && (w.gme ?? 0) < FORGET_UNDER)
+            delete st.watch[a];
+    writeFileSync(path(), JSON.stringify(st, null, 1));
+    console.log(`[gme-rank] the stash (${stash.toFixed(0)} gme) is #${st.rank} among wallets, ${above.length} above it, ${st.of} watched`);
+    return readRank();
+}

package/dist/holders.js

@@ -0,0 +1,122 @@
+// The holder count, from the chain: a balance map kept from every Transfer event since launch,
+// updated incrementally each run (site/holders-state.json). The explorer blocks automated reads.
+// v3 also remembers, per wallet, when it first received $gmerald and whether it has ever sold any
+// (sent tokens into the pool; a transfer to another wallet is a move, not a sell). That is what "check your cheeks" on the site reads. Wallets that empty out are forgotten,
+// so one that leaves and comes back starts over: "joined" is when the current position began.
+import { parseAbiItem } from 'viem';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cfg } from './env.js';
+import { pub } from './chain.js';
+const LAUNCH_BLOCK = 52845715n;
+const VERSION = 3;
+const ZERO = '0x0000000000000000000000000000000000000000';
+// a sell is a transfer into the pool: v4 settles swaps straight into the PoolManager, and the router and
+// permit2 are the only other places a swap can route through. anything else sent out is a move, not a sell.
+const SINKS = new Set(['0x8366a39cc670b4001a1121b8f6a443a643e40951', '0x8876789976decbfcbbbe364623c63652db8c0904', '0x000000000022d473030f116ddee9f6b43ac78ba3']);
+const statePath = () => join(cfg.siteDir, 'holders-state.json');
+const fresh = () => ({ v: VERSION, lastBlock: (LAUNCH_BLOCK - 1n).toString(), balances: {}, first: {}, out: {} });
+export async function readHolders() {
+    let st = fresh();
+    try {
+        const s = JSON.parse(readFileSync(statePath(), 'utf8'));
+        if (s.v === VERSION)
+            st = s;
+        else
+            console.log('[holders] state format changed; rescanning from launch');
+    }
+    catch { }
+    // hourly is plenty for a holder count, and it keeps the state file's commits down
+    if (st.scannedAt && st.count && Date.now() - new Date(st.scannedAt).getTime() < 55 * 60_000)
+        return st.count;
+    const bal = new Map(Object.entries(st.balances).map(([a, v]) => [a, BigInt(v)]));
+    const first = st.first ?? {}, out = st.out ?? {};
+    const latest = await pub.getBlockNumber();
+    let from = BigInt(st.lastBlock) + 1n;
+    const ev = parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)');
+    let step = 5000n, scanned = 0, calls = 0;
+    while (from <= latest && calls < 3000) {
+        const to = from + step - 1n > latest ? latest : from + step - 1n;
+        try {
+            const logs = await pub.getLogs({ address: cfg.token, event: ev, fromBlock: from, toBlock: to });
+            calls++;
+            // newcomers in this span, and the span's clock: the timestamps of its two ends, blocks between them on a straight line
+            const newcomers = new Map();
+            for (const l of logs) {
+                const t = l.args.to.toLowerCase();
+                if (t !== ZERO && !(t in first) && !newcomers.has(t))
+                    newcomers.set(t, l.blockNumber ?? from);
+            }
+            let t0 = 0, t1 = 0;
+            if (newcomers.size) {
+                const [b0, b1] = await Promise.all([pub.getBlock({ blockNumber: from }), pub.getBlock({ blockNumber: to })]);
+                calls += 2;
+                t0 = Number(b0.timestamp);
+                t1 = Number(b1.timestamp);
+            }
+            // every read for this span succeeded; only now does the state change, so a failed span retries cleanly
+            for (const l of logs) {
+                const f = l.args.from.toLowerCase(), t = l.args.to.toLowerCase(), v = l.args.value;
+                if (f !== ZERO) {
+                    bal.set(f, (bal.get(f) ?? 0n) - v);
+                    if (SINKS.has(t))
+                        out[f] = 1;
+                }
+                if (t !== ZERO)
+                    bal.set(t, (bal.get(t) ?? 0n) + v);
+            }
+            for (const [a, b] of newcomers)
+                first[a] = to === from ? t0 : Math.round(t0 + ((t1 - t0) * Number(b - from)) / Number(to - from));
+            scanned += logs.length;
+            from = to + 1n;
+            st.lastBlock = to.toString();
+            if (logs.length < 1500 && step < 20000n)
+                step *= 2n; // roomy: widen
+        }
+        catch (e) {
+            calls++;
+            if (step > 250n) {
+                step /= 2n;
+                continue;
+            } // dense: narrow and retry the same span
+            console.log(`[holders] scan stopped at block ${st.lastBlock}: ${e.shortMessage || e.message}`);
+            break;
+        }
+    }
+    for (const [a, v] of bal)
+        if (v <= 0n)
+            bal.delete(a);
+    for (const a of Object.keys(first))
+        if (!bal.has(a))
+            delete first[a];
+    for (const a of Object.keys(out))
+        if (!bal.has(a))
+            delete out[a];
+    st.v = VERSION;
+    st.balances = Object.fromEntries([...bal].map(([a, v]) => [a, v.toString()]));
+    st.first = first;
+    st.out = out;
+    const n = bal.size;
+    st.count = n;
+    st.scannedAt = new Date().toISOString();
+    writeFileSync(statePath(), JSON.stringify(st));
+    console.log(`[holders] ${n} holders · ${scanned} transfers scanned · through block ${st.lastBlock}`);
+    return n;
+}
+// The board: wallets holding the seat threshold or more, from the last scan. Infra is not a seat.
+const SEAT = BigInt(cfg.seatThreshold) * 10n ** 18n;
+// not seats: the pool manager, the launch locker, the treasury, the machine, ops
+const NOT_SEATS = new Set(['0x8366a39cc670b4001a1121b8f6a443a643e40951', cfg.locker, cfg.stash, cfg.pressWallet, cfg.ops].filter(Boolean).map((a) => String(a).toLowerCase()));
+export function boardSeats() {
+    try {
+        const st = JSON.parse(readFileSync(statePath(), 'utf8'));
+        let n = 0;
+        for (const [a, v] of Object.entries(st.balances))
+            if (!NOT_SEATS.has(a) && BigInt(v) >= SEAT)
+                n++;
+        return n;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+const job = process.argv[2] ?? 'press';
+// dry and claimcheck never sign: the flag is read by env.ts before any module can reach wallet()
+if (job === 'dry' || job === 'claimcheck')
+    process.env.CLOCKWORK_DRY_RUN = '1';
+if (job === 'init') {
+    const { runInit } = await import('./jobs/init.js');
+    await runInit();
+    process.exit(0);
+}
+if (job === 'claimcheck') {
+    const { runClaimCheck } = await import('./jobs/claimcheck.js');
+    await runClaimCheck();
+    process.exit(0);
+}
+if (job === 'handback') {
+    const { runHandback } = await import('./jobs/handback.js');
+    await runHandback();
+    process.exit(0);
+}
+if (job === 'doctor') {
+    const { runDoctor } = await import('./jobs/doctor.js');
+    await runDoctor();
+}
+else if (job === 'press' || job === 'dry') {
+    const { runPress } = await import('./press.js');
+    await runPress();
+}
+else if (job === 'quotecheck') {
+    const { runQuoteCheck } = await import('./jobs/quotecheck.js');
+    await runQuoteCheck();
+}
+else if (job === 'buys') {
+    const { runBuys } = await import('./jobs/buys.js');
+    await runBuys();
+}
+else if (job === 'log') {
+    const { runLog } = await import('./jobs/log.js');
+    await runLog();
+}
+else if (job === 'holders') {
+    const { readHolders } = await import('./holders.js');
+    console.log(`holders: ${await readHolders()}`);
+}
+else if (job === 'tgcheck') {
+    const { runTgCheck } = await import('./jobs/tgcheck.js');
+    await runTgCheck();
+}
+else if (job === 'launchcheck') {
+    const { runLaunchCheck } = await import('./jobs/launchcheck.js');
+    await runLaunchCheck();
+}
+else {
+    console.error(`unknown job: ${job} (use init | press | dry | doctor | claimcheck | holders | tgcheck | log | buys | quotecheck | launchcheck | handback <address>)`);
+    process.exit(1);
+}
+export {};