Combat kernel & treasury microstructure

00 / Bilateral wager allocation and realized performance

An open lobby is an owner-authorized, expiring reservation, not an on-chain escrow transfer. It reserves one fighter’s proposed stake for fifteen minutes. Cancellation or expiry releases the reservation; acceptance atomically replaces it with a persisted bilateral match allocation. BEGIN IMMEDIATE serializes competing acceptances. Both fighters must be enabled, launched, past cooldown, free of pending treasury operations, and within verified earnings and cash caps. Same-wallet opponents are excluded. Manual acceptance requires a healthy worker heartbeat.

Auto acceptance is a separate owner-signed standing authorization with a default of false. The keeper can accept posted wagers within the opted-in fighter’s maximum stake, or pair two opted-in fighters. Every admission rechecks current consent and allocation state. Pausing cancels unaccepted reservations while retaining committed match locks. Funded-performance profit counts successful finalized loser-to-winner settlement movements only, excluding fees, gas deposits, practice outcomes, pending results, and transaction costs. Coin ownership is independent of the fighter beneficiary’s payout entitlement.

reservationLifetime = 900000 ms
P_i = Σ finalizedMatches (1[win_i] − 1[loss_i]) × stake
accept(lobby) ⇒ replace reservation_A with lock_A + lock_B atomically

01 / State space and transition kernel

A match is a finite-horizon stochastic process over two immutable fighter configurations. Each configuration contains five integer stats in [1,10] and exactly four distinct registered abilities. The validator applies componentwise bounds; it does not impose an aggregate stat budget. Styles are initial conditions for stats and loadouts, not a separate damage multiplier or elemental matchup matrix. Element labels carry no resistance multiplier in the current engine.

The combat state includes turn, seed, HP, cooldown vectors, alive flags, guard flags, status-duration vectors, and an event transcript. Initial maximum health is H = 34 + 3v. Energy and gold fields remain in the state representation but are not consumed by the ability engine. Each fighter’s action is chosen by an LLM agent. On every turn the engine sends the model ⟦inputs, e.g. own and opponent HP, cooldowns, status durations, equipped abilities, recent transcript, fighter profile prompt⟧ and expects exactly one equipped ability ID in response. The model is ⟦model name and provider⟧ with ⟦temperature and sampling settings⟧ and a ⟦timeout in ms⟧ timeout. The seeded uniform selector described in section 02 is retained only as a fallback when the model call fails or returns an inadmissible move.

Every step clones the previous state. Guards clear; cooldowns decay; poison applies to living fighters. Poison deaths are resolved before action planning. Each surviving fighter obtains an ability decision, initiative orders the plans, and surviving actors resolve their actions. Status counters decay after resolution. A knockout suppresses an action that has not yet executed.

S(t+1) = T(S(t), C_A, C_B, seed, decision)
H_i = 34 + 3 × vitality_i
initiative_i = 20 × priority(move_i) + effectiveSpeed_i + U_i
decision_i = LLM(S(t), profile_i) if admissible else fallback

02 / Entropy decomposition and action admissibility

Mulberry32 supplies deterministic pseudo-random draws from unsigned 32-bit state. Combat initializes its stream with seed + turn × 9973. Initiative, hit checks, critical checks, and damage jitter consume this stream in execution order; changing an earlier action can therefore change later draw consumption. Move choice is not drawn from this stream. It comes from the LLM decision, so the combat stream is deterministic only conditional on the recorded decisions.

On use, a cooldown is set to configured cooldown + 1; the next round begins by decrementing it. A cooldown of two prevents reuse in the next two rounds. If the model call throws, times out, or returns an unequipped or cooling-down move, selection falls back to a seeded uniform selector over ready equipped abilities. That selector initializes its own stream with seed + turn × 104729 + the sum of the fighter ID’s character codes. If no move is ready, the first equipped ability is the final fallback even if its cooldown remains positive. This makes readiness a normal selection constraint, rather than an absolute no-action condition. The transcript should record whether each action came from the model or from a fallback ⟦confirm this is stored⟧.

Funded matches use the LLM decision function with the seeded selector as fallback, and a server-generated crypto.randomInt 32-bit seed. Candidate ordering is randomized before automatic pairing, which requires both owners to opt into auto accept. Manual lobbies fix an exact stake and require a different wallet owner to accept. This is not skill-based matchmaking, a rating model, or a cryptographic fairness protocol. The operator controls the engine, the model, the prompts, retries, the fallback rule, the candidate set, and seed generation. Deterministic reproducibility of the combat engine does not establish unbiased seed selection or reproducible agent decisions.

action_i = LLM(state_i, profile_i) if valid else seededUniform(ready_i)
moveSeed (fallback) = seed + 104729 × turn + Σ charCode(fighterId)
combatSeed = seed + 9973 × turn
ready = { a ∈ equipped : cooldown(a) ≤ 0 }

03 / Damage functional and temporal effects

Accuracy is tested before damage. For an attack, critical probability is min(0.35, 0.025 × focus + precision bonus), where Precision Shot adds 0.15. Base damage includes effective power and uniform multiplicative jitter; defense is subtracted before rounding. Critical rounding follows base rounding. A guard then applies floor(0.45 × damage), bounded below by one, and is consumed by the hit. A missed attack does not consume the target’s guard, but every guard clears at the start of the next round.

Power boosts add three power; speed boosts add three speed; slow subtracts three speed. Initiative is computed before actions resolve, so a speed change during a round does not reorder already planned actions. New boost counters are four and become three at round end; they remain active for the next three rounds. Slow starts at three and remains for the next two rounds. Poison starts at four and produces three subsequent round-start ticks of two HP. A damage move applies its status even when the target was guarded. Reapplication refreshes duration via a maximum rather than adding stacks.

Second Wind heals min(missing HP, 10 + floor(0.7 × focus)). Drain Strike heals min(missing HP, max(1, floor(actual damage / 2))). Healing never exceeds maximum HP. Guard, healing, and boost abilities still perform accuracy checks according to their registry values. A hit or miss consumes the ability cooldown.

P(hit) = accuracy / 100
P(crit | hit) = min(0.35, 0.025f + bonus)
d₀ = max(1, round((movePower + 0.8 × effectivePower) × (0.9 + 0.2U) − 0.45 × defense))
d₁ = critical ? round(1.5 × d₀) : d₀
d = guarded ? max(1, floor(0.45 × d₁)) : d₁

04 / Horizon, terminal ordering, and presentation clock

One survivor wins; zero survivors is a draw. The standard horizon is forty rounds. At timeout, surviving fighters are ranked lexicographically by remaining HP fraction, base speed, then fighter ID in ascending order. Equal health fractions do not automatically produce a draw: an otherwise exact tie favors A. This deterministic tie-break is part of the result and should be included in any balance analysis.

Replay frames present a result already computed by the worker. Frame spacing is max(2500 ms, ceil(120000 ms / max(1, frameCount − 1))). Funded settlement becomes eligible after the replay duration plus a one-second buffer. The next start is no earlier than max(selected start interval, replay duration + 30 seconds) after the prior start. Selected intervals are 2, 5, 10, or 15 minutes. Two minutes is therefore a replay floor, not a promise of thirty starts per hour.

Practice starts stop while the page is hidden and are disabled on reload; practice never creates monetary claims. Funded participation is persistent server state authorized by the owner and remains enabled when the browser closes. Viewing a page does not schedule a match. Pausing forbids new allocations but does not cancel existing locked stakes.

terminalRank(i) = (HP_i / H_i, baseSpeed_i, ascending ID_i)
Δframe = max(2500, ceil(120000 / max(1, N − 1))) ms
nextStart ≥ start + max(interval, replayDuration + 30000 ms)

05 / Coin topology and authority partition

Registration binds a fighter ID to an owner, a dedicated creator treasury, a mint, a fixed payout beneficiary equal to the owner, token metadata, and the canonical combat configuration. Provisional launch preparation requires no separate wallet message; it reserves one mint per fighter but does not activate ownership or funded jobs. Ownership is established by the owner-signed finalized launch. Launch is an owner-paid Solana transaction built using Pump’s createV2 instruction. The regular SOL quote route is used; mayhem, cashback, and holder-reward modes are disabled. The mint transaction transfers 0.015 SOL from the owner to the treasury and contains no initial buy. A second owner-approved transaction initializes Pump’s native fee-sharing configuration, assigns 1000 basis points to the project treasury and 9000 to the fighter treasury, and revokes share-update authority. Setup rent comes from the fighter treasury. The coin becomes eligible for funded participation only after this finalized configuration is independently checked. Each fighter reserves exactly one mint, including across retries.

The owner pays the creation rent and network costs in addition to the bootstrap. The dedicated creator treasury receives eligible creator-fee claims across Pump and PumpSwap. Fees depend on protocol state and trading activity; this specification does not assume a fixed fee percentage, volume, return, or token appreciation. Token ownership is not a dividend entitlement, treasury ownership, or permission to operate the signer.

Treasury and pre-launch mint secrets are encrypted using AES-256-GCM with fresh 12-byte nonces. Associated data binds ciphertext to its role and fighter ID; decrypted keys must reproduce the expected public key. Treasury keys remain under application custody. The mint secret is cleared from persistent storage after launch verification. SQLite allocations are not on-chain escrow, and owners do not independently control the creator treasury key.

owner = beneficiary
creator = dedicatedTreasury(fighterId)
bootstrap = 15,000,000 lamports
1 SOL = 1,000,000,000 lamports

06 / Capital admissibility and exposure frontier

All economic computations use integer bigint lamports with truncating division. Let B be finalized treasury cash, E be verified unwithdrawn earnings, L be locked stake, W be pending withdrawal, R be the 0.01 SOL gas reserve, and F be the fee allowance. Deposits increase B but do not increase E. The keeper currently budgets F = 50,000 lamports; this is an admission allowance, not a quoted final fee.

Eligible capital is constrained by both cash and earned capital. The stake cap is the smaller of 2% of eligible capital and available cash after the fee allowance. A computed cap below 0.001 SOL is zero. Consequently the smallest stake needs at least 0.05 SOL of eligible capital, not merely the 0.015 SOL launch deposit. Owner-selected stakes of 0.001, 0.005, and 0.01 SOL are ceilings; the actual matched stake can be lower and is the minimum of both ceilings and both computed caps.

A pair is admitted only when both fighters are launched, opted in, due, free of existing match locks, and free of pending non-launch operations. Creator routing is revalidated. The SQLite transaction records the match and establishes logical locks for both treasuries. Gas reserve and lock checks also precede actual settlement. A failed affordability check makes the pair wait; it does not fabricate rewards or borrow from the owner’s connected wallet.

C = max(0, B − R − L − W)
Q = max(0, min(C, E − L − W))
cap = min(floor(Q × 200 / 10000), max(0, C − F))
cap < 1,000,000 ⇒ cap := 0
s = min(ceiling_A, ceiling_B, cap_A, cap_B), s ≥ 1,000,000

07 / Settlement algebra and fee drag

Both sides logically lock s lamports, but settlement sends only the losing stake to the winner’s treasury. The winner’s own stake is released. A draw releases both without a transfer. Protocol commission is zero. A winner therefore earns +s, not +2s; the loser spends s and the settlement transaction’s costs. Quoting a two-stake pot describes allocation conservation, not a two-stake on-chain payment to the winner.

For a fixed stake and a simplified binary-outcome model with win probability p and loser-paid transaction fee f, expected match gain is (2p − 1)s − (1 − p)f. At p = 0.5 this is negative by f/2 before creator revenue and other operating costs. The implied break-even win probability is (s + f)/(2s + f). These equations are analytical approximations: actual costs vary, stakes change, outcomes are correlated, and draws are possible. They are not calibrated forecasts.

Across a closed pair, match transfers conserve principal and burn network costs. Creator fees are the external inflow; owner payouts are the external outflow. A profitable combat record does not establish profitable token trading or positive owner returns after creation costs. There is no emissions budget that pays a fixed amount for merely simulating more fights.

A wins: ΔA = +s; ΔB = −s − f_B
B wins: ΔA = −s − f_A; ΔB = +s
draw: ΔA = ΔB = 0 (no settlement transaction)
EV ≈ (2p − 1)s − (1 − p)f
p_break-even ≈ (s + f) / (2s + f)

08 / Claims, withdrawals, and liquidity segmentation

The persistent keeper loops roughly every fifteen seconds. Fee eligibility checks are spaced by five minutes per fighter, and payout eligibility checks by one hour; these are checks, not guaranteed execution times. Collection skips pending operations and match locks. Simulated claim proceeds must be at least 0.001 SOL net of transaction costs. Final accounting credits no more than the smaller of the positive observed treasury balance delta and the original quoted claimable amount, preventing unrelated rent refunds or deposits from being classified as creator revenue.

Withdrawal protects gas reserve, locked stakes, pending withdrawals, transaction costs, and a 0.05 SOL bankroll while funded battles are enabled. When participation is disabled, the bankroll requirement is zero. A payout must be at least 0.01 SOL and goes only to the immutable owner beneficiary. A treasury can have a positive balance yet have no eligible payout because that balance is deposited capital, reserved capital, locked capital, or below the payout threshold.

Claims, funded outcomes, payout amounts, and paying-treasury network fees update the persistent earnings ledger only after verified finalized transactions. RPC failure or ambiguous submission is a pending/unavailable state, not zero earnings or success. Availability depends on a functioning worker, sufficient gas, protocol compatibility, and eventual transaction finality.

K = enabled ? 50,000,000 : 0
withdrawalQuote = min(B − R − L − W − K − F, E − W − L − K − F)
withdrawalQuote < 10,000,000 ⇒ payout := 0
claimNet < 1,000,000 ⇒ defer claim

09 / Authorization, receipt verification, and replay resistance

Owner authorizations are Ed25519 signed messages bound to the application origin, Solana network, wallet, action, a readable intent, SHA-256 payload digest, nonce, and expiry. Nonces expire after five minutes and are consumed once. The public launch flow prepares transactions without an off-chain registration or launch message; the owner must sign each exact transaction, and the RPC relay validates every required signature against its stored prepared message hash. Funded settings remain a distinct signed-message action. Legacy signed registration/launch endpoints remain compatible. Settings approval authorizes managed treasury activity within the specified participation and stake ceiling; it is not a token spending approval for the owner wallet.

Launch verification checks the successful finalized transaction message against a stored prepared message hash, then checks the mint’s actual creator and supported curve mode. Settlement and payout verification require the expected signature, successful transaction metadata, an exact parsed System Program transfer from the expected source to destination for the expected positive amount, and compatible source and beneficiary balance changes. A signature alone is insufficient.

A funded settlement carries a memo containing its match ID and SHA-256 hash of the stored replay JSON. This links a receipt to the recorded transcript. It does not prove unbiased randomness, committed matchmaking, honest off-chain execution, or the absence of unpublished matches. Reproducing combat given the recorded decisions requires the same configurations, seed, and engine implementation. Reproducing the decisions themselves is not possible from the seed, because model outputs depend on model version, sampling, and provider behavior. The replay JSON should include per-turn prompts, raw model responses, parsed moves, and fallback flags ⟦confirm what is actually stored; if prompts and responses are not stored, state that plainly⟧. The replay hash is a commitment to serialized data, not a zero-knowledge proof and not proof that the model produced those outputs.

payloadDigest = SHA256(JSON.stringify(payload))
replayCommitment = SHA256(stored replay JSON bytes)
settlementMemo = fighterfi:match:<matchId>:<replayCommitment>

10 / Operation journal and crash consistency

A signed transaction, expected signature, blockhash, last-valid block height, operation amount, and semantic details are persisted before broadcast. Reconciliation searches signature history, waits through intermediate confirmation, verifies finalized results, and applies accounting once. If a send times out, the worker rebroadcasts the same signed bytes, retaining the same transaction identity instead of issuing a second payment.

When a transaction is absent and finalized block height exceeds its stored validity limit, the operation may be marked expired and rebuilt. A confirmed but not finalized transaction is not rebuilt merely because wall-clock time passed. Failed settlements return their match to the retryable playing state. Prepared or submitted operations prevent overlapping non-launch jobs for the same paying fighter.

SQLite uses WAL, foreign keys, a busy timeout, and immediate transactions for allocations and accounting. A keeper lease coordinates workers against the same database; persisted operation identities and stake locks provide recovery state. Deployment assumes persistent storage on one host, with a web process and background worker sharing the database. Key and database backups are required to recover custodial funds. This is an operational trust boundary, not a globally distributed consensus layer. The same boundary covers the agent: the operator controls the model, prompts, retries, and fallback behavior, and changes to any of them shift win rates in real-stake matches.

prepared → submitted → confirmed
prepared/submitted → failed | expired
match: playing → settling → confirmed
match draw: playing → draw
ambiguous send ⇒ retain signature and signed bytes

11 / Observable quantities and research discipline

Useful combat quantities include win rate by loadout and side, knockout round distribution, timeout frequency, critical frequency conditional on hits, ability selection frequency conditional on readiness, guard absorption, poison contribution, healing efficiency, and the fraction of turns resolved by the fallback selector rather than the model. Any benchmark should report the configuration matrix, seed set, engine revision, model version, sampling settings, prompt template, fallback rate, sample size, and A/B side assignment. Reverse side assignments when measuring matchup strength because fallback selector salts and the final tie-break depend on identity.

For n binary trials, the sample estimate is p̂ = wins/n and the elementary independent-trial standard error is sqrt(p̂(1 − p̂)/n). This approximation does not validate independence or repair biased seed selection. Draws require an explicit scoring convention. Monte Carlo combat estimates characterize the chosen engine, agent, and sampling process; they do not predict token volume, creator revenue, or realized mainnet profitability.

Treasury analysis should separate gross creator claims, net claimed proceeds, funded match transfer P&L, transaction costs, locked capital, deposits, withdrawals, and available cash. A balance screenshot collapses these distinct quantities. Receipt verification establishes transfers; off-chain canonical records establish intent. The public UI currently presents balances, stakes, matches, and receipts; the statistical diagnostics described here are a methodology, not an implemented analytics dashboard.

p̂ = wins / n
SE_independent ≈ sqrt(p̂(1 − p̂) / n)
Δcash = deposits + net creator inflows + match transfers − payouts − other operating costs

12 / Ability parameter registry

Rendered directly from the engine registry. Power is base damage for damage moves and base healing for heal moves. Priority contributes twenty initiative units per point. Cooldown is measured in subsequent excluded rounds.