clockwork-press 0.2.0 → 0.2.2

package/dist/config.js

@@ -53,6 +53,10 @@ export function validate(c) {
         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

@@ -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,
+    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/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' },
-        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,11 +356,32 @@ 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);
     const minPress = parseUnits(cfg.minPressGme, cfg.pairDecimals);
     let unsweptOut = '0';
+    let escrowOut = '0';
     // 1. Fees reach the escrow only after a sweep: on the curve they accrue as balances on the curve, in
     //    the pool as pendings on the hook. The numbers are read in every mode; only auto mode sweeps,
     //    claims and releases (manual: the founder claims by hand and the machine presses what it is sent).
@@ -357,9 +407,18 @@ async function pressOnce(runAt, commit) {
     if (u.tokenSide > 0n)
         console.log(`[press] ${fmtTok(u.tokenSide)} ${cfg.tokenSymbol} of fees wait on the hook too; only the pons operator converts those`);
     const o = await tryRead('escrow', () => owed(me), { pair: 0n, token: 0n });
+    // a claim costs gas and posts a card, so the machine waits for the claim floor, and claims whatever waits
+    // at least once every `atLeastEveryHours` so small fees never sit forever
+    const claimFloor = parseUnits(String(cfg.claimFloor), cfg.pairDecimals);
+    const lastClaimTs = readLedger().presses.filter((p) => (p.kind ?? 'press') === 'press').at(-1)?.ts;
+    const hoursSinceClaim = lastClaimTs ? (Date.now() - new Date(lastClaimTs).getTime()) / 3_600_000 : Infinity;
+    const claimDue = o.pair >= minPress && (o.pair >= claimFloor || hoursSinceClaim >= cfg.claimEveryHours);
+    escrowOut = fmtPair(o.pair, 4);
     if (o.pair >= minPress && !auto)
         console.log(`[press] the escrow holds ${fmtPair(o.pair, 4)} ${cfg.pairSymbol} for the machine (claim mode manual: not claimed by the machine)`);
-    else if (o.pair >= minPress) {
+    else if (o.pair >= minPress && !claimDue)
+        console.log(`[press] the escrow holds ${fmtPair(o.pair, 4)} ${cfg.pairSymbol} for the machine; claims at ${cfg.claimFloor} ${cfg.pairSymbol} or after ${cfg.claimEveryHours}h (last claim ${hoursSinceClaim === Infinity ? 'never' : hoursSinceClaim.toFixed(1) + 'h ago'})`);
+    else if (claimDue) {
         const got = pairNum(o.pair);
         commit();
         const tx = await claimPair();
@@ -415,7 +474,7 @@ async function pressOnce(runAt, commit) {
             }
         }
     }
-    const watched = () => ({ ...common(), feeRecipient: watch.feeRecipient, pendingRecipient: watch.pendingRecipient, unswept: unsweptOut });
+    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/package.json

@@ -1,9 +1,9 @@
 {
   "name": "clockwork-press",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",
@@ -17,7 +17,8 @@
     "bin",
     "README.md",
     "LICENSE",
-    "npm-shrinkwrap.json"
+    "npm-shrinkwrap.json",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/clockwork/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: clockwork
+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.
+---
+
+# ClockWorks, with an assistant next to you
+
+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/
+
+## Rules you follow, without exception
+- **Never ask for, read, print, store, or type a private key or a bot token.** The human pastes them on
+  GitHub's secrets page or into a `gh secret set` prompt in their own terminal. If a key appears in the chat,
+  tell the human it is burned and to create a fresh wallet.
+- **Never send funds and never sign.** You prepare transactions; the human signs them in their own wallet.
+- **Never create wallets or accounts for the human.** Tell them what to create and where.
+- The treasury wallet must not be the machine wallet. The machine wallet must be fresh, funded with a little
+  ETH for gas, and never a main wallet.
+
+## What you need from the human before you start
+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 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) 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.1 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
+   in this file; it is public by design.
+2. **Create the repository.** Open https://github.com/MithrilDaniel/clockwork-template and click
+   "Use this template", public or private, any name. Replace its `clockwork.json` with the one from step 1.
+3. **Set the secrets.** Repository Settings, Secrets and variables, Actions, New repository secret:
+   `MACHINE_WALLET_KEY` (the machine wallet's private key) and, for Telegram, `TELEGRAM_BOT_TOKEN`.
+   Or from their terminal: `gh secret set MACHINE_WALLET_KEY -R <owner>/<repo>` (it prompts and hides the
+   value). You never see these values.
+4. **Dry run.** Actions tab, the "clockwork" workflow, "Run workflow", job = `dry`. Read the log with the
+   human. Expect: the peg line, the holders line, `launch: pool` or `curve`, where fees go, what is unswept,
+   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
+   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;
+   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
+   `https://api.github.com/repos/<owner>/<repo>/actions/workflows/press.yml/dispatches` with body
+   `{"ref":"main"}` and a fine-grained GitHub token scoped to that one repository, for punctual ticks.
+7. **The status page** is live at `https://gmerald.xyz/clockwork/m/?r=<owner>/<repo>` after the first tick
+   commits. Every number on it is read from the repository the machine writes to.
+
+## Reading a run
+- `ran N min ago, the next tick is not due; leaving`: the double-tick guard. Nothing wrong.
+- `X gme of fees unswept, and they are not ours to sweep`: fees sit on the pons hook until pons sweeps
+  them into the escrow. The machine claims what the escrow holds. Ask pons how often the operator sweeps.
+- `fees no longer point at the machine`: the recipient changed. If the founder did it, fine. If not, they
+  open pons and check, and they can run `clockwork handback <address>` from a machine that is still the
+  recipient to move fees to a wallet of their choice.
+- `the key is for 0x…, but clockwork.json names 0x…`: the wrong key was pasted. Set the secret again.
+- `holding: …`: the launch is between phases (swept or rescued); the machine holds the slice.
+
+## 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 ·
+`handback <address>` claim what is credited, then move the fee recipient · `holders` the holder count.
+
+## 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.