F FORGE
FORGE AGENT

Protocol

Fee-vault keeper

Goal

Anyone can call claimAndSplitNative / claimAndSplitToken and earn callerTipBps of the post-platform beneficiary pool (MVP default 1% / 100 bps). That tip is paid to msg.sender in the same asset being split so vaults stay drained without relying on a single operator.

The tip is never taken from the platform cut. Platform always receives its full platformFeeBps of gross first.

FORGE also runs its own keeper inside apps/worker so claims still happen reliably when public bots are quiet — but the keeper only submits a tx when the expected tip covers gas + configured profit.

On-chain economics (per claim)

text
platformAmount    = gross * platformFeeBps / 10_000           // default 15% of gross
beneficiaryPool   = gross - platformAmount                    // default 85% of gross
callerAmount      = beneficiaryPool * callerTipBps / 10_000   // default 1% of beneficiary pool → msg.sender
beneficiaryAmount = beneficiaryPool - callerAmount

Caller cannot redirect platform or beneficiary shares; tip is the only incentive and comes solely from the beneficiary pool.

Keeper decision rule

For each vault + asset (native or approved ERC-20):

  1. Read claimable balance from PONS escrow for that vault (and any already-sitting vault balance).
  2. Estimate tip = (claimable - platformAmount) * callerTipBps / 10_000

equivalently (claimable * (10_000 - platformFeeBps) / 10_000) * callerTipBps / 10_000.

  1. Estimate gas for claimAndSplit* (with buffer), gasCost = gasEstimate * maxFeePerGas (native).
  2. Convert tip to native (identity if native asset; else oracle/DEX quote with haircut).
  3. Submit only if tipValueNative >= gasCost + minProfitNative.
text
KEEPER_MIN_PROFIT_WEI=...          # absolute floor profit after gas
KEEPER_GAS_BUFFER_BPS=2000         # 20% gas estimate padding
KEEPER_TIP_HAIRCUT_BPS=500         # 5% discount on ERC-20 tip valuation
KEEPER_POLL_INTERVAL_MS=30000
KEEPER_MAX_TX_PER_TICK=10
KEEPER_PRIVATE_KEY=                # worker-only; never in web/api

If unprofitable: skip (log skip_unprofitable). Public callers may still claim smaller amounts for altruism or bundling — that is fine.

Worker job

apps/worker job fee-vault-claim-keeper:

  • Scan indexed vaults with non-zero escrow/claimable (from indexer + RPC).
  • Rank by estimated net profit descending.
  • Send claim txs from the keeper key (or flashbots/private relay later).
  • Idempotent: unique per (vault, asset, block) attempt; do not blindly retry ambiguous timeouts for state-changing calls without receipt checks.
  • Index NativeSplit / TokenSplit (including callerAmount) for transparency UI.

Public path

  • UI “Claim fees” / API POST /agents/:id/fees/claim returns an unsigned permissionless call the user’s wallet can send (they earn the tip from the beneficiary pool), or enqueues a keeper evaluation (no guarantee of immediate claim if unprofitable).
  • Do not require the beneficiary to be the caller.

Safety

  • Keeper key is worker-env only; minimal ETH balance; no other privileges.
  • Never share keeper key with Agent LLM tools.
  • Quote sources for ERC-20 tip valuation must be allowlisted; fail closed (skip) if quote missing.
  • Admin can tune callerTipBps (max 5% of beneficiary pool) if public claiming is under/over incentivized.