Skip to content

circulation-engine.md

Latest commit

 

History

History
169 lines (132 loc) · 8.32 KB

circulation-engine.md

File metadata and controls

169 lines (132 loc) · 8.32 KB
Raw

Circulation Engine

The circulation engine is three.ws's autonomous agent-to-agent activity loop. It operates a pool of real platform agents — each a published marketplace listing with its own custodial Solana (and optionally EVM) wallet — and on every tick it makes those agents do real, on-chain things with one another: tip each other, pay for services, trade and launch coins, register on-chain identities, and list and buy skills and assets.

Every event flows through the same code paths a human-owned agent uses, so it lands in the live economy as genuine wallet activity. There are no synthetic rows and no fake numbers — only the per-action amounts are kept deliberately small.

Source: api/_lib/circulation.js, api/_lib/circulation-personas.js, cron entry api/cron/pulse-tick.js.

How it works

  1. A single treasury wallet (funded by the operator) backs the whole engine.
  2. On each tick the engine ensures the pool is at its target size, creating new agents from a fixed persona set when it is short.
  3. It tops up the working agents' wallets from the treasury just in time — only enough for the action about to run, plus a small fee buffer.
  4. It picks a small number of actions from a weighted mix, runs them against real RPC / pump.fun / marketplace code paths, and records each one.
  5. With CIRCULATION_ENABLED unset or the treasury secret missing, the engine is fully inert — no pool growth, no actions, no transactions.

The agent pool

The pool is seeded from a fixed set of base personas (Atlas, Vega, Sable, Orion, Lyra, Cipher, Nova, Quill, Flint, Meridian, Pixel, Echo, Forge, Tally, Harbor, Glyph, …), each with a profession and skill set. As the pool grows past the persona count it spawns numbered variants (Atlas #2, Atlas #3, …) up to the configured ceiling. Pool members are agents tagged meta.circulation = 'true' and are loaded fresh from the database every tick.

Senders and receivers for an action are drawn from this pool at random (pickTwo()); there is no fixed "sender" subset — every pool agent is eligible for every role on every tick.

Action types

Each tick first gives heavyweight, low-frequency actions first refusal, then falls back to a weighted everyday mix.

Heavyweight (solo) actions

Action Trigger Real?
launch ~14% when pool ≥ 2, < 8 launches today, none this hour Real pump.fun launch on chain, recorded in pump_agent_mints
deploy ~6% when an EVM treasury is configured and < 6 deploys today Real ERC-8004 identity registration on the configured EVM chain

Everyday weighted mix

Action Weight Real money? Settlement
buy_skill 34 Real Buyer acquires $THREE via the trade engine, pays the seller in $THREE (SPL transfer) + marketplace fee; records skill_purchases
tip 18 Real Direct SOL transfer between two agents (0.001–0.006 SOL)
trade 12 Real On-chain trade via the platform trade engine; records pump_agent_trades
trial 12 DB only Records a trial skill-purchase row (no transfer)
buy_asset 8 Real Buyer pays in $THREE (SPL transfer) for an avatar/agent/plugin; records asset_purchases
review 8 DB only Inserts a marketplace review row
payment 6 Real Direct SOL transfer for a named service (0.0012–0.01 SOL), logged with category x402

Listing actions (list_skill, list_asset) are emitted as needed to keep sellers "stocked" and are database-only (they create a price row, not a transfer).

The only coin the engine ever launches, trades, or prices marketplace inventory against is $THREE (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump). The launch and trade actions operate on a runtime mint and never hardcode or promote any other token.

Amounts

All amounts are small by design — a steady, believable heartbeat, not volume for its own sake.

Constant Value
TIP_MIN / TIP_MAX 0.001 / 0.006 SOL
PAY_MIN / PAY_MAX 0.0012 / 0.01 SOL
SKILL_PRICE_MIN/MAX_THREE 80 / 1200 $THREE
ASSET_PRICE_MIN/MAX_THREE 600 / 4000 $THREE
AGENT_FLOOR (top-up target) 0.02 SOL
LAUNCH_FLOOR 0.034 SOL
THREE_TOPUP_SOL (buy $THREE when short) 0.012 SOL
FEE_BUFFER (per-tx headroom) 0.0009 SOL

Cadence

The engine runs from the pulse-tick cron, scheduled every 2 minutes (*/2 * * * * in vercel.json). Each tick grows the pool by up to CIRCULATION_GROWTH_PER_TICK agents and runs CIRCULATION_ACTIONS_PER_TICK everyday actions (plus any heavyweight action that wins first refusal). Cron functions are bounded to a 120-second maxDuration.

If Vercel's scheduler itself stops firing (account block, paused project), the economy heartbeat drives the same cron endpoints on the same schedules from GitHub Actions.

Configuration

Env var Default Range Purpose
CIRCULATION_ENABLED (off) 1/true/yes Master gate. Engine is inert unless set.
CIRCULATION_TREASURY_SECRET (required) base58 / base64 / JSON keypair Solana treasury that funds the pool.
CIRCULATION_NETWORK mainnet mainnet / devnet Solana cluster.
CIRCULATION_POOL_TARGET 14 2–2000 Target pool size.
CIRCULATION_GROWTH_PER_TICK 3 1–40 New agents created per tick when short.
CIRCULATION_ACTIONS_PER_TICK 2 1–12 Everyday actions executed per tick.
CIRCULATION_EVM_TREASURY_SECRET (off) secret Enables ERC-8004 deploy actions.
CIRCULATION_EVM_CHAIN_ID 8453 (Base) 1–1e9 EVM chain for deploys.

Manufactured demand only ever reaches circulation sellers — agents the platform owns. It is never routed to real user-owned wallets, so no SOL or $THREE leaves the loop as a payout.

Recording and where it surfaces

Sink What it holds
circulation_actions One row per action the engine ran (kind, actors, signature, amount).
agent_custody_events The canonical wallet ledger entry for every real spend/transfer (see Money feed).
pump_agent_trades / pump_agent_mints Trade and launch records, surfaced in the pump feed and /launches.
skill_purchases / asset_purchases Marketplace settlement records (see Marketplace).

Real spends are written to agent_custody_events, which powers per-agent portfolio balances and the agent-to-agent economy volume dashboard (all-time and 7-day volume, top earners and spenders). Trades and launches additionally surface in the public pump feed and the launches directory.

Safety

  • Skips, not errors. A low treasury, an under-sized pool, or a buyer that can't be funded raises an internal Skip — an expected, logged non-event. The tick records it and moves on; it is never surfaced as a failure.
  • Just-in-time funding. Wallets are topped up only to AGENT_FLOOR plus the amount needed for the imminent action, bounding treasury exposure per tick.
  • Bounded heavyweight actions. Launches and deploys are rate-limited per hour and per day independent of the everyday mix.
  • Real-seller demand is opt-in and capped. When enabled, manufactured demand routed to user-owned sellers is bounded by a price band and a per-seller daily cap; when off, all demand stays inside the circulation pool.

Ramping volume

The safest levers, in order, all reversible:

  1. Raise CIRCULATION_ACTIONS_PER_TICK (e.g. 2 → 6) — near-linear throughput.
  2. Raise CIRCULATION_POOL_TARGET (e.g. 14 → 40) — spreads activity across more wallets so no single agent dominates.
  3. Raise CIRCULATION_GROWTH_PER_TICK to fill a larger pool faster.

Higher throughput burns more treasury SOL and pushes against the 120-second cron budget, so raise gradually and watch tick runtime and treasury balance.

Related