ClockWorks, from first principles.

overview.

ClockWorks runs a token's creator fees on Robinhood Chain. A launch on pons v2 earns a fee on every trade, and the creator claims it by hand. ClockWorks claims it on a clock, splits it by percentages the founder set once, burns the burn share in slices, sends the treasury share to a wallet the software never sends from, and prints every transaction hash where anyone can read it.

The machine runs in the founder's own GitHub repository, on a wallet the founder created. ClockWorks has no key to it. The code is published as a package, and the repository pins the exact version it runs. Nothing changes under a machine unless its owner changes the number.

It ran first on GMERALD, a token paired with tokenized GameStop stock, live since 2026-09-06. Every transaction its machine sent is on gmerald.xyz.

lifecycle.

Every tick follows the same four steps. There is no path where the machine decides to do something different.

Inside one tick, in 0.4.4, the order is fixed: finish any slice a failed run left half sent, read the stock guard, claim, count the day's claims toward the step, pay the board if a drop is due, on a stock pair sell what is held for ClockWorks (see what changed in 0.4.4), then slice. Before a slice with a burn share sends any leg, it checks that its burn leg can run; when it can't, the whole slice waits and nothing is split (see what changed in 0.4.3).

the split.

Five shares that add up to one hundred. Burn buys the token and destroys it; on a native ETH pair it stays at 0 until 0.5.0. Treasury goes to the founder's treasury wallet, and the software never sends from it. Ops, when set, goes to a wallet the founder spends from. The board, when set, waits in the machine wallet and is paid to seats once a day; see the board. ClockWorks' share is sent on chain by the machine, slice by slice; see the price. The chain is the invoice.

three presets.

The settings page shows three splits side by side. None is chosen until you click one, and the board stays off unless you pick it. Each writes all five keys, with ClockWorks at 10%, and shares what is left. Which three depends on the pair. On a USDG or WETH pair:

On a native ETH pair there is no burn leg until 0.5.0, so burn stays at 0: burn and treasury becomes treasury, and board and keep half give the burn's share to the treasury.

Any split that adds up works, with burn at 0 on a native ETH pair, and a preset never touches the board rule. Keep half needs an ops wallet, which is the creator's own. From 0.4.2 its ops leg moves on every slice when the pair has no dollar price feed. When pair.usdFeed is set, the ops leg waits in the machine wallet until the peg check passes and goes out with the next slice's ops leg. While it waits it is never sliced again.

the price.

10% of claimed creator fees, and 5% on the part of a UTC day above a step. No setup fee, no subscription. clockwork-press 0.4.5 serves pons tokens paired with USDG, WETH, native ETH or one of 23 Robinhood stock tokens. The machine's service leg pays it on chain, slice by slice (on a stock pair as USDG, sold from the share set aside), and handback ends it.

an example day.

how a day is counted.

• Only what the pons fee escrow paid the machine wallet counts, read from the escrow's own logs. The day is the UTC date of the block the claim landed in, never the run's clock.
• Money the machine did not claim itself is charged 10% as it is sliced: claims made by hand with claim.mode manual, deposits, and fees claimed elsewhere and sent in.
• The step never changes the ratio between your other legs. They share what ClockWorks does not take, in the ratio of their numbers.
• On a machine's first run on 0.4.2 or later, claims made earlier that UTC day are not counted, so on that one day the step is reached later.
• Stock pairs are served from 0.4.4, with a step of their own. ClockWorks' share is never sent in the stock: each slice sets it aside in the machine wallet, and once a tick the machine sells what is held for USDG on a pinned pool, only when the pool's price sits within 3% of a price anchor, and sends the USDG. GMERALD, the house's own machine on a GameStop stock pair, runs as before and pays no service share.

the floor.

split.serviceBps is the rate up to the step, and 1000 is the lowest a file may set. A file at 1500 pays 15% up to the step and 10% above it. No value in clockwork.json lowers the floor, and service.minBps is ignored. This is the floor the ClockWorks License points to. The one exception is GMERALD, the house's own machine, which sets its own share.

the board.

An optional share for holders, off unless the founder sets one, paid once a day. Every slice holds back the board's share of itself in the machine wallet. What is held is never sliced or burned; it waits there for the day's drop.

At the first tick after 00:00 UTC, everything held is paid to every seat, in the pairing asset, by balance: a seat holding twice as many tokens gets twice as much. A seat is a wallet holding at least the seat threshold, 250,000 tokens by default. Infrastructure is never a seat: the pool, the pons contract that holds launch supply, the treasury, the machine wallet and the ops wallet. The founder lists any other wallet that should not be paid under board.exclude.

the board rule.

board.rule says which balance a seat is paid on. It is new in 0.4.2, and a file without it runs as before.

Under the lowest rule, a scan that fails or stops short changes nothing and never adds or removes a seat. If no complete scan has landed since the last drop, the drop waits, and every tick tries again with a fresh scan. A lower seat threshold takes full effect from the next window. boardcheck and dry print the seats under either rule and write nothing.

A drop is a set of plain transfers, up to 80 a tick, so a large board finishes over a few ticks. A seat whose share is under the minimum payout, 0.0005 of the pairing asset by default, is skipped that day, and its part stays held for the next drop. A drop that stops part way resumes on the next tick from the last seat it recorded. On a stock pair, a seat the issuer blocked is never paid; see the stock guard. Every drop is a row in board-ledger.json, with the rule it used and one line and one hash per seat, and the Telegram group gets one card when it finishes. GMERALD's board is the live example.

quick setup.

Three bundles on the settings page set the claim rule, the pace, the dip mode, the guardrails and the cards in one click. They never set the split, and any knob can still be turned afterwards.

The default floor is the one init writes: 5 for a stock, 100 for a stable, 0.05 for ETH.

the pace.

One control. Gentle spreads a claim over a day. Steady, the default, spreads it over six hours. All at once burns it in one slice. Under "advanced": a fixed slice size, a dollar floor, buying harder on dips, slippage, quiet hours. Most machines never open it.

the treasury.

The treasury share is sent to an address the founder named. ClockWorks has no key to it, and the software has no function that sends from it. On the status page the treasury shows its balance, its rank among holders of the pairing asset, and the average price the fees were claimed at. If anything is sent out of it, the status page turns red for a week and the group gets one card per transfer.

On a stock pair the token's issuer can pause or block it, so the treasury's balance is not the software's to promise. The stock guard reads both.

fees to the machine.

On pons, creator fees go to whoever is named as the fee recipient. Naming the machine wallet is what makes claiming automatic. A founder who prefers to keep claiming by hand can skip this: the machine runs on whatever it is sent, and what it did not claim itself is charged 10% flat.

The machine claims when at least the claim floor waits in the escrow, five of the pairing asset by default, and at least once a day whatever is there. A claim costs gas and posts a card, so it is a real event, not a tick. Both numbers are in clockwork.json.

ClockWorks reads the recipient every run. If fees stop pointing at the machine, or a change is pending in pons's timelock, the status page turns red and the Telegram group gets one card. The machine keeps burning what it holds and claims nothing new until fees point back.

community takeovers.

A takeover wallet is a fee recipient like any other. Once the multisig points fees at a machine wallet, ClockWorks runs the community's fees the same way it runs a creator's. Nothing else about the token changes.

buybacks.

A launch with pons buybacks on collects its own token in the pons buyback vault. ClockWorks takes what the vault has released to the machine and burns it with the next slice. A founder can turn this off and hold instead, under buyback in the config.

payouts.

ClockWorks keeps the book: every payout a listed distributor sent to holders, read from the chain as Transfer events from its wallet, grouped into drops, and priced with the Chainlink feed at the block each drop landed. A holder pastes a wallet and gets a statement, a card and a CSV. Nothing is signed or connected; the book is public files, read in the browser.

Some listed distributors are pons fee-sharing contracts, which pay holders in the pairing asset. A drop is a batch payout: three or more wallets paid in one transaction, from a wallet on the list. A distributor moving its own money, one wallet at a time, stays out. The list lives in distributors.json next to the book, and a distributor that is not on it can be listed by sending its wallet and the token.

The job that writes the book is read-only, needs no key and runs anywhere; its command is payouts. It keeps a block cursor per distributor and reads only what is new, so an hourly run takes a few seconds. PAYOUTS_DIR names where the book is written.

the stock guard.

Robinhood's stock tokens share one blocklist and one pause switch, both set by their issuer. From 0.4.2 the machine reads them before any stock token moves. The guard turns itself on when the pair is a Robinhood stock token and never runs for ETH, WETH or USDG pairs. There is nothing to configure. From 0.4.4 any machine on one of the 23 pinned stock tokens runs it too. The ClockWorks wallet is not on the guard's list there: it never receives the stock, because the share is sold for USDG before it is sent.

Receipts in a stock token record the issuer's share multiplier beside the raw amount, and drop lines record the amount with it applied. On a day with nothing paused and nothing blocked, the guard changes nothing. It covers GMERALD's GameStop stock pair too.

setup, self-serve.

Five steps, about fifteen minutes, and only one of them asks for a terminal, which you can skip. A founder with an assistant hands it the ClockWorks skill and answers its questions.

1. A machine wallet. Create a fresh wallet on your own device and send it about 0.02 ETH on Robinhood Chain for gas. Never a main wallet. Nobody at ClockWorks ever sees its key.
2. The config, built in your browser. Read your fee report first: paste your token address on the start page. Then open the settings page with ?t=<your token address>. It reads the launch from the pons factory and fills every knob with the defaults. Choose a split: one of the three presets, or your own numbers that add up to 100; nothing is chosen for you. Add the machine wallet and the treasury wallet. Create the repository from the template, name it on the page, and paste a fine-grained GitHub token for that one repository (Contents read and write). The page writes clockwork.json into it as one commit, and the token stays in your browser. The file is public by design and never holds a key. (The terminal way still works: npx --yes clockwork-press@0.4.4 init <your token address> writes the file with the split left for you to choose.)
3. The key. Repository settings, Secrets and variables, Actions: add MACHINE_WALLET_KEY. For your own Telegram bot, add TELEGRAM_BOT_TOKEN too. GitHub keeps them, and the machine reads them at run time. This is the one step no page can do for you, because the page would have to see the key.
4. Dry run, then fees to the machine. Actions tab, the "clockwork" workflow, Run workflow, job = dry. The log shows the launch, where fees go, what is unswept, and what a real tick would burn. It refuses to run if the key belongs to a wallet other than the one in your config. Then claim what is already credited to you in pons, because a recipient change does not move it, and use the point page: from the wallet that receives fees today, it prepares the one transaction that points them at the machine. The pons UI does not show this function; the contract has it, and it takes effect immediately.
5. Live. The workflow's schedule ticks on the quarter hour. Your status page is at gmerald.xyz/clockwork/m/?r=<owner>/<repo> the minute the first tick commits, and the machine index on the start page lists you from the first payment the chain shows.

Punctual ticks. GitHub's own schedule can run a few minutes late. For ticks on the minute, add a cron-job.org job that POSTs to your repository's workflow dispatch URL with a fine-grained GitHub token scoped to that one repository. The workflow leaves when another tick committed less than ten minutes before, so two clocks never burn twice.

Telegram.

Every claim and every slice lands in your group within the minute, with your art. Two minutes to set up.

1. In Telegram, open @BotFather, send /newbot, and give it a name and a username. It replies with a token. Add the token to your repository as the secret TELEGRAM_BOT_TOKEN, nowhere else.
2. Add the bot to your group as an admin so its posts survive anti-spam bots.
3. Run the workflow once with job = tgcheck. The log prints the group's chat id. Put it in clockwork.json under telegram.chatId, with telegram.mode set to own.
4. Your art: brand.art takes one image or short mp4 URL per card: claim, slice, percent, buy, newHolder. Without one, the card is text only. The words on the cards follow brand.treasuryWord, brand.burnWord and brand.claimWord, so a token can use its own words.

Cards on by default: the claim, the slice, and every whole percent of supply burned. The buy card, with new-holder detection, is off by default and has a dollar floor. On a stock pair the guard adds one card per pause, per blocked wallet and per multiplier change. No links in the cards; hashes live on the status page.

running off GitHub.

clockwork.json.

One file the founder owns. Addresses in it are the audit. Every job except init checks the file before it runs, and the machine refuses to run when the split does not add up, when the wallet on disk is not the wallet in the file, or when a paying config runs on a build whose service wallet is not pinned. Edit it by hand, or on the settings page, which shows every knob, checks them the way the machine does, and saves one commit to your repository with a GitHub token that stays in your browser.

There is no field for the price, the step, the stock guard or a preset's name. The step is looked up by the pair's address, never by its symbol.

commands.

Every command runs from the folder that holds clockwork.json, with Node 20 or newer. Nothing here needs a key except press, board and handback, which read it from the environment the workflow provides.

In a repository made from the template, the same jobs run from the Actions tab: Run workflow, then pick the job. The version lives in one place, the workflow's pin.

contracts, Robinhood Chain (4663).

what the machine refuses.

A split with burn, treasury, ops and board all at 0: choose a split. A split that does not add up, or a key in it that is not a whole number from 0 to 10000. A ClockWorks share under 10% on any machine but GMERALD's. A board rule that is neither at-drop nor lowest-since-last-drop. A pair whose decimals do not match USDG (6) or WETH (18). From 0.4.3, a burn share on a native ETH pair, on any machine: native ETH pairs have no burn leg until 0.5.0: set burnBps to 0 and give that share to the treasury, the board or ops. And on any machine but GMERALD's, a pair other than USDG, WETH or native ETH: clockwork-press 0.4.3 serves pons tokens paired with USDG, WETH or native ETH; stock-token and other pairs come in a later release. A key in the repository that is not the machine wallet in the config. A service share above zero on a build with no service wallet. A pool quote further from the market than the sanity band. A second tick less than the cadence after the first. Each refusal is a line in the run log, and none of them moves money. One hold sits beside them: a slice with a burn share whose burn leg can't run that tick waits whole, and the status reads holding: the burn leg can't run (<reason>), so nothing is split.

what changed in 0.4.5.

0.4.5 fixes three findings of the 0.4.2 review before any client runs them. None had happened on a live machine. Nothing in clockwork.json changes; the board ledger's lines gain two fields.

• A seat is never paid twice. A drop's transfers were sent and the line written after the receipt, so a run killed between the two (a runner's timeout, a lost process) would have resumed the drop and paid that seat again. Now each transfer is signed first, its hash written into the line (pending), then sent; the next tick asks the chain about every pending line before it pays anyone. A hash that landed is the payment; one the chain never saw stays on the line as tried while a fresh transfer goes out.
• One drop a day, whichever write a kill fell between. The day was marked right after the drop was written; a run killed between the two would have opened a second drop. The day's drop is now read from the board ledger too, and a resumed drop marks its day.
• The holder scan's span is clamped between 250 and 20,000 blocks, the rule the step scan already followed.
• A holder scan under way is saved every 25 chunks. A new machine's first scan is long, and a run killed in the middle of it used to start over. It now carries on from the last save, and the board opens no drop until that first scan has finished.
• The pin. The template's workflow runs clockwork-press@0.4.5. A machine moves to it only when its owner changes the pin. The refusal for an unserved pair now begins "clockwork-press 0.4.5 serves".
• The checks. 31 checks against the built package on a stub chain, with a run killed after its first transfer and a scan killed part-way, and the same checks run against 0.4.4 to show they fail there.

what changed in 0.4.4.

0.4.4 serves tokens paired with a Robinhood stock token again, for every machine, by changing where ClockWorks' share goes on such a pair. No field is added or renamed in clockwork.json and no default changes. Nothing changes for GMERALD, the house's machine: it pays no service share, so nothing is set aside and the swap never runs. The contract is docs/CONFIG-0.4.4.md in the package's repository.

• The pin. The template's workflow runs clockwork-press@0.4.4. A machine moves to it only when its owner changes that number.
• 23 stock tokens. AAPL, AMD, AMZN, COIN, COST, DJT, GLD, GME, GOOGL, MSFT, MSTR, MU, NU, NVDA, PLTR, RBLX, SGOV, SNAP, SNDK, SPCX, SPY, TSLA and UPS, each pinned in the package with a USDG pool (16 on uniswap v4, 7 on v3), a Chainlink price feed where one exists, a step and a cap. Any other pair is still refused: clockwork-press 0.4.4 serves pons tokens paired with USDG, WETH, native ETH or a Robinhood stock token it has a USDG route for (…); other pairs come in a later release.
• ClockWorks' share on a stock pair is set aside, then sold for USDG. A Robinhood stock token is a Regulation S security the ClockWorks wallet never receives. Every slice records its share (serviceHeldGme) and holds it in the machine wallet, out of the float, the way the board's share is held. Once a tick, after the board's drop, the machine sells what is held on the pinned pool and sends the USDG to the ClockWorks wallet. Both transactions are signed and written down before they are sent, so a run that stops between them never sends twice.
• The sale waits until it is checked. The stock guard must hold nothing and the issuer's oracle must not be paused; the price anchor must answer (the Chainlink feed at most 36 hours old, or dexscreener's volume-weighted price on the seven stocks with no feed); the pool's own quote must sit within 300 bps of it; at most 2,500 USD a swap (500 on a thin pool), and nothing under 10 USD. The reason it waits is in press-stats.json under service.waiting, and doctor prints the route, the anchor, the pool's gap and what is held.
• A step for stock pairs: the shares that were worth 2,000 USD on 2026-09-14 (2.625 SPY, 9.3015 NVDA, 94.9848 GME), pinned, so a stock-pair client pays the stepped price like everyone else.
• Two new refusals on a stock pair: decimals other than 18, and a pair.usdFeed that is not the feed the package pins (init writes the pinned one).
• The board never pays seats out of what is held for ClockWorks or for ops; the guard leaves the ClockWorks wallet out on a stock pair.

what changed in 0.4.3.

0.4.3 fixes two billing defects a review found in 0.4.2 before any client ran it. No field is added or renamed and no default changes. Nothing changes for GMERALD, the house's machine: a GME pair with no service share, which neither refusal touches.

• The pin. The template's workflow runs clockwork-press@0.4.4. A machine moves to it only when its owner changes that number.
• No burn share on a native ETH pair. On a native ETH pair 0.4.2 skipped the burn leg but still sent the other legs. The burn share stayed in the machine wallet, joined the next run's float, and was split and charged ClockWorks' share again. 0.4.3 refuses such a file on every machine: native ETH pairs have no burn leg until 0.5.0: set burnBps to 0 and give that share to the treasury, the board or ops.
• A slice whose burn leg can't run waits whole. Before any leg is sent, a slice with a burn share checks that its burn leg can run in this run. When it can't (a native ETH pair, or the pool with the v4 swap off, or a curve buy that would cross into graduation and hand part of the burn share back), no treasury, service, board or ops transfer goes out, the float waits in the machine wallet, and the status reads holding: the burn leg can't run (<reason>), so nothing is split. A launch between the curve and the pool, or a rescued one, keeps its own hold words, as in 0.4.2. Claims, the step count and the board's drop still run.
• USDG, WETH and native ETH pairs. On a stock-token pair 0.4.2 would have sent the service leg in the stock token itself. 0.4.3 refuses every other pair on every machine but GMERALD's: clockwork-press 0.4.3 serves pons tokens paired with USDG, WETH or native ETH; stock-token and other pairs come in a later release. init still writes the file, and prints that line as a note.
• The presets on a native ETH pair. Burn and treasury becomes treasury: treasury 9000, ClockWorks 1000. Board: board 4500, treasury 4500, ClockWorks 1000. Keep half: ops 4500, treasury 4500, ClockWorks 1000. USDG and WETH pairs keep their three, and init still writes a split of 0 on every pair until one is chosen. See three presets.
• The price and the board rule work as in 0.4.2 on the pairs 0.4.3 serves, and the stock guard works as in 0.4.2 on GMERALD's machine.

what changed in 0.4.2.

0.4.2 folds in 0.4.1. Every 0.4.1 config file loads under it, and nothing is renamed.

• The pin. The template's workflow runs clockwork-press@0.4.2. A machine moves to it only when its owner changes that number.
• The price. 10% up to the step and 5% above it on USDG, ETH and WETH pairs, 10% flat on stock pairs. See the price.
• The board rule. board.rule is new, and at the drop stays the default. See the board rule.
• The stock guard. A paused token or a blocked machine wallet holds the tick; a blocked seat is skipped and logged. See the stock guard.
• Exact approvals. Permit2 may pull exactly what the swap in hand spends, for about ten minutes, signed inside the swap itself. The pair token's allowance to Permit2 is bounded by what the burn legs need, never unlimited. The first 0.4.2 slice replaces the unlimited allowances earlier versions set.
• Keep half. The ops leg now moves on USDG and ETH pairs. Before, with no dollar feed, it never moved there: it was sliced again and charged ClockWorks' share twice.
• Stock amounts. Receipts in a stock token record the issuer's share multiplier beside the raw amount.
• The words. The package README calls the treasury a wallet the software never sends from. It used to say the treasury only grows, but a stock token's issuer can pause or block it, so that is not the software's to promise. The claim card now states a dated fact read from the chain, where it used to say the treasury share was never sold and never distributed.
• These docs. This page described 0.4.2 when it shipped. Running a machine off GitHub is not yet documented.

security.

One machine, one repository, one wallet, one key. The lines below describe clockwork-press 0.4.3. The ones about custody and pinning were first checked against GMERALD's machine on September 6, 2026, and the checks are repeatable on any machine.

no custody.

The key is a GitHub Actions secret in your repository. Secrets are scoped to one repository; another repository, another workflow, or ClockWorks cannot read them. The machine only ever signs as the wallet named in your config, and refuses to run when the key belongs to any other wallet.

nothing shared between machines.

Machines do not know about each other. There is no server between them, no shared database, no shared wallet. The ClockWorks wallet that receives the service share is a constant in the package, never in a config, so no file can redirect a share to a different address.

pinned code.

The workflow runs an exact version of the package, 0.4.3 in the template, with a lockfile that pins every dependency, and installs with lifecycle scripts disabled. The two GitHub actions it uses are pinned by commit hash. Releases are published by hand and carry no npm provenance record yet; the code that runs is the published tarball, readable on npm. One setting a template cannot carry, so set it on your repository: Settings, Actions, General, allow GitHub-owned actions only. GMERALD's repository has it.

money moves in small steps.

Burns happen in slices at the pace you chose. Each swap is quoted first and refused when the pool quote is further from the market than the sanity band, or when slippage would exceed the cap. Approvals are exact: Permit2 may pull only what the swap in hand spends, for about ten minutes, and the pair token's allowance to Permit2 is bounded, never unlimited. A tick that fails after a transfer writes what landed, and the next tick finishes the row. A second tick inside the same quarter hour is refused.

the software never sends from the treasury.

The treasury share is sent to an address you named. ClockWorks has no key to it, the software has no function that sends from it, and it refuses a config where the treasury is the machine wallet or the zero address. On a stock pair the token's issuer can still pause or block it; the guard reads both, and the outflow watch reports any transfer out.

the recipient watch.

Every tick reads who receives your fees and whether pons has a recipient change pending. If fees stop pointing at the machine, the status page turns red, the group gets one card, and the machine claims nothing new until they point back.

what can go wrong, honestly.

Nobody at ClockWorks can see your key. A GitHub Actions secret is encrypted at rest, decrypted only inside the runner for the minutes a job runs, and masked in every log. The only code that touches it is the package we publish, pinned by exact version, dependencies locked, install scripts off, and anyone can read the published code on npm.

What can expose the key: your own GitHub account being taken over, or a malicious version of the package, which pinning prevents unless someone bumps the pin. So keep two-factor on GitHub. And the design keeps the blast radius small: the machine wallet holds only the float between a claim and its slices, never the treasury. A stolen machine key could also send what the board is holding for the day's drop, and could redirect the fee stream; the collector contract below was planned to remove that last risk and has not been built.

shipped, and what was not.

Two of three landed in 0.2.2 on September 6: a treasury-outflow watch that posts one card per transfer out of a treasury wallet and turns the status page red for a week, and a low-gas card once a day when the machine wallet runs low. The third, a collector contract owned by the founder's cold wallet so that a leaked machine key could never move a fee stream, was planned for that week and was never built. Every machine runs with that risk, stated here rather than hidden.

support.

The package is public on npm and the repository a machine runs in is the template, under the ClockWorks License: source-available, run it yourself, and keep the service share at or above the floor. Questions go to @gmeraldexe until ClockWorks has a group of its own.