FORGE Smart Contracts — MVP

0. Final contract source style (required)

No comments in final Solidity. Production / deployable contracts under packages/contracts (and anything verified on-chain) must ship with zero //, ///, or /* */ comments — including NatSpec. Behavior and invariants live in this doc, Foundry tests, and off-chain docs only.

• docs/contracts/*.sol may keep brief comments as a readable reference while the product is specified.
• When copying into packages/contracts for build, deploy, or explorer verification: strip all comments.
• SPDX license lines and pragma stay; do not use comment blocks as documentation on-chain.

1. Scope

FORGE does not replace PONS token-launch contracts in MVP. FORGE adds only contracts needed for transparent platform economics and later utility.

MVP contracts:

1. AgentFeeVault
2. AgentFeeVaultFactory
3. ForgeLaunchRouter — atomic vault create + PONS launch in one user transaction

Phase 1.1:

1. ForgeBoostBurner (optional dedicated burn/boost proof contract)
2. staking/utility contracts only after economics and audit are finalized

1.1 Atomic vault + token launch (required)

Creators must not sign two separate transactions (vault deploy, then PONS launch). MVP ships a ForgeLaunchRouter that, in a single msg.sender call from the creator wallet:

1. AgentFeeVaultFactory.createVault(agentId, beneficiary) (CREATE2)
2. Calls PONS launchToken / launchAndBuy with creatorFeeRecipient = vault

Initiator / salt namespace: The router must preserve PONS’s initiating-wallet semantics the same way the official launch-and-buy router does (trusted-forwarder / launchTokenFor-style path). Salt namespace, deployer attribution, and predictLaunchAddresses must use the creator wallet, not the router address. If PONS only allows that pattern through its published router interface, wrap it; do not invent a path that makes the router the deployer.

ECA (Expected Contract Address) simulate — required UX before Launch:

Before the user clicks Launch, a Compute / Simulate addresses action (no wallet signature) must return and display:

Also pin and show: salt, expectedEconomics (from previewLaunchEconomics), launch fee, pair asset, vault beneficiary, and current fee disclosure (live platformFeeBps + callerTipBps — default 15% of gross to platform, then 1% of the beneficiary pool to the claim caller).

Launch-intent then builds one unsigned tx to ForgeLaunchRouter using those pinned values. Re-simulate if beneficiary, salt, launch config, or pair token changes. Intent expires; stale economics must force a fresh simulate.

2. AgentFeeVault

Purpose: be the PONS creatorFeeRecipient, claim creator proceeds from the PONS fee escrow and split claimed assets between FORGE, the permissionless claim caller, and the Agent beneficiary.

Default MVP split (admin-editable)

Tip is not taken from the platform cut. Order:

platformAmount     = gross * platformFeeBps / 10_000     // default 15% of gross (untouched)
beneficiaryPool    = gross - platformAmount              // default 85% of gross
callerAmount       = beneficiaryPool * callerTipBps / 10_000  // default 1% of beneficiary pool
beneficiaryAmount  = beneficiaryPool - callerAmount      // default 99% of beneficiary pool

Platform always receives its full BPS of gross. The 1% tip comes only from what would otherwise go to the beneficiary.

Permissionless caller tip (required)

• Any address may call claimAndSplitNative / claimAndSplitToken (and the split-only helpers).
• Caller cannot redirect platform or beneficiary shares.
• Caller receives callerTipBps of the post-platform beneficiary pool (default 1%) in the same asset.
• Tip is paid to msg.sender in the claim/split transaction.

FORGE keeper (required)

FORGE runs its own keeper in apps/worker that evaluates every vault and only submits a claim tx when the caller tip covers estimated gas + configured profit. Public bots may still claim anytime. Full rules: Fee keeper.

Admin control

• platformFeeBps and callerTipBps live on AgentFeeVaultFactory, mutable by factory admin (setPlatformFeeBps, setCallerTipBps).
• Vaults read BPS live at claim/split time so admin updates apply on the next claim.
• Caps: MAX_PLATFORM_FEE_BPS = 3000 (30% of gross), MAX_CALLER_TIP_BPS = 500 (5% of beneficiary pool). Independent — tip does not reduce platform.
• setPlatformRecipient admin-only. Prefer multisig admin before real value.
• CREATE2 vault ECA does not include BPS in initcode.
• UI / CLI / /config/public must show live BPS values and state that tip is from beneficiary share, not platform.

Properties:

• owner = launching creator wallet (set at deploy; not the ForgeLaunchRouter, not factory admin)
• beneficiary mutable by vault owner via setBeneficiary (migrate wallets / action contracts post-launch)
• ownership transferable via transferOwnership (e.g. to a multisig)
• PONS escrow immutable per vault
• platform fee BPS, caller tip BPS, and platform recipient admin-editable on factory (FORGE admin — cannot set vault beneficiary)
• CREATE2 salt is agentId only (one vault per agent); constructor includes owner + initial beneficiary
• permissionless claim/split with 1% caller tip; caller cannot redirect other shares
• nonReentrant
• native and ERC-20 handling
• emit BeneficiaryUpdated / OwnershipTransferred and detailed split events
• do not hold balances intentionally

3. Who can change what

Disclose on fee transparency: current beneficiary, vault owner, and that owner can update beneficiary on-chain. Index BeneficiaryUpdated so the UI stays current.

UI/API: authenticated creator (matching vault owner) gets unsigned setBeneficiary / transferOwnership txs from My Agents settings.

4. Agent action destination

The beneficiary share (post-platform pool minus caller tip) may be:

• EOA/multisig controlled by Agent creator
• a creator-owned smart account
• an independently audited Agent action contract

Owner may point beneficiary at a new address after launch. FORGE does not make downstream action guarantees. The UI clearly displays current beneficiary, whether it is a contract, and vault owner.

5. Boost burning

For Phase 1.1, prefer an event-emitting contract over sending to an arbitrary dead address if you want strong campaign attribution:

burnForBoost(agentId, amount, packageId)

Contract should transfer/burn FORGE and emit:

BoostBurned(address payer, bytes32 indexed agentId, uint256 amount, uint8 packageId)

Backend only enables a campaign after event confirmation and price-package validation based on the server's quote policy.

6. Security requirements before mainnet value

• Foundry tests + fuzzing (including admin fee updates mid-stream)
• static analysis
• independent contract review/audit
• verify source on explorer
• deploy deterministic known bytecode
• multisig for factory admin + platform recipient once real value exists
• no proxy unless upgradeability is genuinely required
• no generic delegatecall/call execution in fee vault
• ERC-20 transfers via SafeERC20
• handle fee-on-transfer/rebasing tokens conservatively; for PONS approved quote assets, test explicit behavior
• do not assume ERC-20 returns standard booleans without SafeERC20
• admin cannot set platform BPS above MAX_PLATFORM_FEE_BPS or tip above MAX_CALLER_TIP_BPS
• factory admin cannot redirect vault beneficiary share
• only vault owner can setBeneficiary / transferOwnership
• caller tip always goes to msg.sender of the claim/split and is carved only from the beneficiary pool

Invariant examples:

• platform + callerTip + beneficiary amount == gross
• platformAmount == gross * platformFeeBps / 10_000 (tip never reduces platform)
• callerAmount == (gross - platformAmount) * callerTipBps / 10_000
• claim caller cannot alter beneficiary or platform recipient
• only vault owner can change beneficiary / ownership
• only factory admin can change platform BPS / caller tip BPS / platform recipient
• no unprivileged path can withdraw beneficiary or platform shares to a third party

7. Economic disclosure

Platform fee = platformFeeBps of vault gross. Claim caller tip = callerTipBps of the post-platform beneficiary pool (not of gross, not of platform). UI must say this clearly and refresh when admin changes BPS.

Admin APIs: POST /admin/fees/platform-bps, POST /admin/fees/caller-tip-bps. Chain is source of truth for splits. Keeper policy: Fee keeper.