脈ticker bot
kagura's clock is currently advanced by an off-chain process calling tick_funding on a schedule. this page is what to run, how, and what to watch.
the shipped script
scripts/tick-loop.ts is a long-running process that reads deploy.json, opens an anchor provider, and calls tick_funding on a configurable interval.
1ANCHOR_PROVIDER_URL=https://api.devnet.solana.com \2ANCHOR_WALLET=$HOME/.config/solana/id.json \3TICK_LOOP_MS=1500 \4yarn ts-node scripts/tick-loop.tsinterval policy
- recommended: 1000 to 2000 ms. solana's clock has 1-second resolution, so anything below 1000ms wastes calls (elapsed_ms rounds to 0 and the on-chain accrual is the same as a longer interval).
- upper bound: don't exceed the registered
tick_interval_ms. Going slower means longer accrual cycles per call (still mathematically correct) but worse user-perceived smoothness. - cost: each tick is one tx ≈ 5,000 lamports priority fee. 1.5s cadence ≈ 57,600 tx/day ≈ 0.29 SOL/day at base fees, less if you right-size priority.
error handling
The shipped tick-loop catches errors, logs, and continues. Categories you'll see:
| error | meaning | action |
|---|---|---|
Blockhash not found | RPC out-of-sync | retry next tick (auto) |
ProtocolPaused | operator paused kagura-core | halt ticker, alert |
VaultPaused | operator paused vault | halt ticker, alert |
ClockRegression | solana clock anomaly | shouldn't happen on mainnet; alert |
TreasuryExhausted | reserve drained | top up treasury, ticks resume automatically |
treasury exhaustion behavior
kagura-vault's tick_funding uses min(accrued, treasury_balance). When the treasury hits zero, ticks succeed but transfer 0. The vault is paused-by-economics rather than paused-by-flag. The ticker should still run (so when treasury is topped up the next tick captures the right elapsed_ms).
restart policy
- run under a process supervisor:
systemd,pm2,tmux+ restart-on-exit, or kubernetes Deployment. - single instance per vault. running two tickers is harmless (both compete to win the next slot) but wastes RPC calls.
- if you redeploy programs, the ticker keeps working because PDA addresses don't change.
permissionless ticker (future)
v1 of kagura-core requires the protocol authority to sign record_tick. v2 will drop that constraint. Once shipped, anyone with sol can advance any registered protocol's clock — useful for community-run uptime, MEV searcher participation, and resilience against operator failure.