Contracts

PlannedChecked 16 November 2026

In short

  • Five contracts, tested on a local chain only.
  • What can never change, and what the owner can change.
  • Not audited, not deployed.

Not deployed. No contract on this page is on any chain. There are no addresses, no RPC settings, no keys and no deploy scripts in the repository. No token has been bought, sold or moved. The contracts run only on a local test chain inside the test run (npm run contracts:test, Hardhat, solc 0.8.28). For the plain overview, see the coin.

The PETROVA token itself would be made by Bankr on Base. The token contract is not in this repository, so nothing here can prove its supply or that it cannot be minted. The contracts below are what would sit behind the one address Bankr pays creator fees to, plus the contract customers would buy credits through.

Before anything goes live (none done): an outside audit of these contracts and of a real swap router adapter (not written yet); a written decision on the real numbers; confirming with Bankr how fees are paid; explicit approval to deploy.

The contracts

Sources: contracts/src/. Tests: contracts/test/*.test.js.

FeeSplitter: the address Bankr pays

  • Bankr fees (ETH, WETH, PETROVA): 50% to the BuybackBurner, 50% to the Reserve.
  • Petrova's USDC fee share: 10% to the BuybackBurner, 20% to the AllowancePool, 10% to PETROVA stakers (paid pro rata to locked units through the AllowanceLock), 60% to the Reserve. With no units locked, the stakers' share goes to the Reserve.
  • Anyone can call distribute. The three destinations are fixed when the contract is made.
  • The burner and pool parts round down; the Reserve gets the exact remainder. Nothing is left behind.
  • Any other token can only go to the Reserve.

Test: "gives the odd wei to the reserve so nothing is left behind"; "routes exactly, deposits into the pool with an event".

CreditPurchase: customers buy credits with USDC

  • A purchase is customer money. It goes whole to a fixed custody address (Petrova's deposit account, not the Reserve) and becomes the customer's balance. Nothing is split at purchase time.
  • Petrova's fees are split later, when they are earned, by the FeeSplitter's USDC route above (stakers are paid from that 10%, never from deposits).
  • No owner, no admin, no pause. The contract keeps no balance: it pulls the exact amount, forwards it in the same transaction, and refuses fee-on-transfer tokens.

The app follows the same rule. A credited top-up records no split. Every movement of Petrova's fee revenue (the platform_revenue ledger account: at settlement, and negative when a refund or a true-up gives fee back) records the FeeSplitter USDC shares in fee_splits (migration 028), not yet routed on-chain. Tests: tests/integration/wallet.test.ts, "top-up: pending until N confirmations, then credited once with a balanced journal and no FeeSplitter share (a deposit is not fee revenue)"; tests/integration/trueup.test.ts, "fee revenue, not deposits, is what the FeeSplitter shares are recorded on, and a true-up that gives fee back splits negatively". Gap: the app records the stakers' 10% even when no units are locked; the contract would send it to the Reserve.

BuybackBurner: buys PETROVA and burns it

  • Once per UTC day, anyone can run it. It buys PETROVA with WETH and USDC and sends all of it to 0x000000000000000000000000000000000000dEaD.
  • Each swap must return at least the quote minus the slippage limit, checked against the burner's real balance. Otherwise the whole run is undone.
  • There is no withdraw function.

Tests: "wraps ETH, buys with WETH and USDC, burns everything to the dead address"; "can run only once per UTC day, by anyone"; "has no way to withdraw funds".

AllowanceLock: lock PETROVA, get allowance units

  • One unit costs a fixed number of PETROVA (tokensPerUnit), set once at creation.
  • A lock lasts 365 days (LOCK_DURATION). After that you can take your PETROVA back or renew for another 365 days.
  • Adding units restarts the 365 days for your whole position.
  • Nothing can be unlocked within 24 hours of your latest lock (STAKE_COOLDOWN), even after the 365 days. This stops someone locking borrowed PETROVA and returning it in one transaction.
  • New units are accepted only when the AllowancePool holds at least 60 days of allowance for every unit, including the new ones (ReserveTooLow otherwise).
  • An expired position shows 0 active units until it is renewed or unlocked. Its PETROVA still earns USDC rewards while it stays locked.
  • Staker rewards (USDC). distribute(amount) shares USDC across the units locked at that moment, pro rata. A later locker gets none of an earlier distribution. With nobody locked, the USDC goes to the treasury. claimRewards() pays out what you earned; earned(address) shows it.
  • No owner, no admin, no pause.

The daily allowance per unit is a setting on the AllowancePool (dailyAllowancePerUnit), fixed when the pool is made. The target is $1 a day per unit; the number is not decided. Nothing in the app reads unitsOf yet, so a lock does not add anything to a Petrova balance today.

Tests: "publishes the fixed tokens-per-unit and 12-month duration"; "has no owner or admin functions".

AllowancePool: the USDC behind the units

  • Anyone can deposit. Only the payout role can take USDC out, never more than a daily cap.
  • New units are allowed only if the pool holds at least 60 days of allowance for all units, including the new ones.

Tests: "only PAYOUT_ROLE can withdraw, and never above the daily cap"; "requires balance >= 60 x daily obligation including new units, exactly".

What cannot change

ContractCannot change
FeeSplitterThe token addresses and the three destinations (burner, reserve, pool)
BuybackBurnerThe token addresses; the burn address; no withdraw; slippage limit never above 5%
AllowanceLockEverything: token, tokens per unit, pool, 365-day lock. No owner
AllowancePoolUSDC address, allowance per unit, the 60-day rule; the lock can be bound once

What the owner can change

This is the part that is not fixed. contracts/README.md describes one share change (the USDC burner share from 10% to 20%). The code allows more than that.

ContractOwner powerDelay
FeeSplitterSet any split, including 0% to the burner and 100% to the Reserve7 days, visible on-chain, can be cancelled
BuybackBurnerChange the swap router7 days
BuybackBurnerChange slippage (up to 5%)None
BuybackBurnerChange the most spent per run, including to 0, which stops buybacksNone
AllowancePoolLower the daily payout capNone
AllowancePoolRaise the daily payout cap7 days

Ownership moves in two steps (the new owner must accept). The slippage check compares against the router's own quote, so a router that can be moved in the same block weakens it. Both points need the audit above.

Corrections to contracts/README.md

The contracts are not changed here (another lane owns them). These are the exact statements the README must carry, each checked against contracts/src/:

  1. FeeSplitter. Replace "Changing a share: the owner proposes, everyone can see it on-chain for 7 days, and only then can the owner apply it" with: "After a 7-day delay the owner can set any split: proposeShares accepts any burn and pool shares that sum to at most 100% (_validate), including 0% to the BuybackBurner and 100% to the Reserve, and proposeStakerShare can set the stakers' share to 0%. The change is visible on-chain for 7 days and can be cancelled; nothing limits what it can be."
  2. BuybackBurner pause. Add: "The owner can stop buybacks immediately, with no delay: setMaxSpendPerRun(token, 0) for WETH and USDC makes every run spend nothing. Only the router change waits 7 days."
  3. Slippage. Replace "checked by looking at the burner's real balance, not by trusting the router" with: "The minimum is computed from the router's own quote (router.quote), then the burner's real balance is checked against that minimum. A router that quotes low (or a pool moved in the same block before the quote) sets a low minimum that the balance check then accepts. The balance check proves the router delivered what it quoted, not that the price was fair."

Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.