Pumpologia

The preceding sections are the v0.2 doctrine and public whitepaper body. The following appendix integrates the full technical material extracted from the supplied PDF draft, while treating strict message formats, version fields, internal identifiers, reservations, allocation details, test vectors and state-root mechanics as specification material rather than the protocol edge.

Whitepaper body: minimal human grammar. Appendix: strict validation, derived handles, prototype compatibility and consensus-grade invariants.

We model Bitcoin as an ordered sequence of blocks

where each block contains ordered transactions, and each transaction contains vin[i] inputs, vout[j] outputs, amounts in sats, scripts, and optionally an OP_RETURN output.

Pumpologia does not modify Bitcoin rules. A transaction that is invalid for Bitcoin does not enter the Pumpologia model. A transaction that is valid for Bitcoin may be non-protocol, accepted, rejected, pending, or ignored by Pumpologia.

Let Θ be the set of public protocol parameters: version, supported operations, oracle profile, unit precision, carrier thresholds, settlement rules, reorg policy, and risk functions. The indexer is a deterministic function: FΘ(B0:h) = (σh, E0:h, rh), where σh is the protocol state after block h, E0:h is the derived event log, and rh is a canonical state root.

Invariant 1 (Public history, public state). Given identical Θ and identical Bitcoin history, two independent implementations must produce the same state, the same events, and the same state root.

This requirement is the operational formulation of the principle: the same Bitcoin history plus the same public rules produces the same game state.

For v0, messages are UTF-8 JSON objects in an OP_RETURN output. A Pumpologia message carries at minimum:

The transaction is rejected by the protocol if it contains more than one Pumpologia message. Outputs are scanned in index order; a non-Pumpologia OP_RETURN is ignored; a Pumpologia message with an unsupported version is rejected. The OP_RETURN expresses intent; it carries neither spend authority nor protocol value.

An actor is not a legal identity or a wallet label. It is a deterministic script fingerprint:

For position creation, the actor is derived from the scriptPubKey of the carrier output. For a spending operation, the actor is derived from the scriptPubKey of the spent prevout. For settlement, the payee is derived from the script of the paid output, then compared with the assigned route.

A UTXO becomes protocol-relevant when it is referenced by an accepted operation or when it descends from a carrier, a debt carrier, or a lineage lock. Its live representation must remain bounded:

UTXOProtocolState {
  outpoint
  sats
  clean_sats
  recognized_proof_atoms
  proof_surplus_atoms
  deficit_atoms_total
  claim_atoms_total
  dominant_deficit_ids[]
  locked_sats_by_lock_id[]
  backing_exponent
  risk_exponent
  component_count
  state_class
}

The specification must distinguish historical proof state, which may be richer, from live state, which must remain compact to resist fragmentation attacks.

The minimal classes are: Semantic Class clean UTXO admissible as clean backing.

recognized_carrier Active carrier of a recognized proof/position.

overcollateralized Present backing greater than the notional being played.

proof_surplus Recognized claims or proof greater than local sats.

degraded Carrier that has lost recognition.

deficit Open unsettled loss.

debt_carrier Explicitly eligible UTXO carrying bounded debt.

mixed Clean value and dirty components mixed together.

lineage_locked Descendant blocked by a lock.

quarantined Non-admissible state, too small or too complex.

settled Debt restored or lineage made admissible again.

Invariant 2 (Exponent typing). An exponent has no standalone meaning. It must always be interpreted together with the state_class. A high exponent on a clean position may mean overcollateralization; on a debt carrier it measures debt concentration; on a mixed output it is diagnostic and non-admissible.

Sats are Bitcoin's native unit. Proofs are represented by high-precision integers, for example: 1 $proof = 108 proof_atoms.

This granularity prevents rounding attacks when deficits are fragmented across thousands of outputs. No consensus calculation must use floating-point numbers. Amounts, prices, heights, and indexes are integers.

For a, b ∈ N>0, define: floorLogTenRatio(a, b) = max{k ∈ N : a ≥ 10^k b}, valid when a ≥ b, and: ceilLogTenRatio(a, b) = min{k ∈ N : a ≤ 10^k b}.

These functions replace ⌊log10(a/b)⌋ and ⌈log10(a/b)⌉ without floating point.

The live model must reduce the normal surface to three families: trade, settle, and recover when dirtiness or a lock requires explicit repair. For a fresh position, the message may be:

"side":"long","out":0,"amt":"600","order":"market"} If no protocol input is referenced, the indexer interprets tx.vout[0] as the initial carrier, derives the actor from its script, derives the initial proof capacity according to the v1 rules, fixes the oracle context, and opens the trade. Conceptually, the position and the mint are a single act: POSITION_OPENED.

If a trade spends an existing carrier, in references tx.vin[i], and out references the continuation output:

"side":"short","in":0,"out":0,"amt":"600","order":"market"} The carrier state moves from the prevout to the output. Unreferenced change outputs do not automatically become active protocol states. This rule is essential: a Bitcoin wallet may produce many outputs, but Pumpologia must not create recognition on every output by omission.

A market open enters at the deterministic oracle price of the confirmation block. A limit open is recorded as pending_open, then triggers if the oracle price reaches the condition during the lock window. For a long limit open, entry triggers if Pt ≤ Plimit; for a short, if Pt ≥ Plimit. Closes follow the inverse logic: a long limit close triggers if Pt ≥ Plimit; a short limit close if Pt ≤ Plimit.

The lock field is a positive number of blocks measured from the order's confirmation block. If the condition is not met by created_height + lock, the order expires. Explicit cancellation remains an open question for the live version.

A trade open is invalid if:

sats;

For a fixture version, with integer amount q, entry price p0, and exit price p1:

PnL_long = trunc0(q * (p1 − p0) / p0)
PnL_short = trunc0(q * (p0 − p1) / p0)

The final formula must specify the price scale, rounding rules, gain/loss bounds, and the matching or aggregate settlement model. The non-negotiable principle is that PnL is calculated only after two executed prices have been fixed: entry and exit.

If PnL > 0, the trade creates a claim:

claim_id = sha256("{trade_id}:claim")
amount = pnl
open_amount = amount
status = open

A claim is a settlement right. In the prototype, it does not immediately increase proof capacity; in a more advanced version, liquid claims may become margin assets under an explicit haircut.

If PnL < 0, the trade creates a deficit:

deficit_id = sha256("{trade_id}:deficit")
amount = abs(pnl)
open_amount = amount
status = open

The losing carrier is degraded: its recognition decreases by the amount of the deficit, the deficit is attached to it, and the lineage becomes dirty for later settlement and recovery rules.

Invariant 3 (Causal birth). No claim can exist without winning PnL. No deficit can exist without losing PnL. No settlement can restore capacity without paying the associated canonical route.

$proof must be understood as proof of win. It represents a protocol-level recognition of future sats, arising from a trading history anchored in Bitcoin. It is not a balance edited by a private database: every recognized unit must be able to point to a protocol event and, ultimately, to Bitcoin transactions and deterministic oracle prices.

A winner can therefore have: P > S, where P is the recognized proof and S is the carrier's local sats. The surplus max(P −S, 0) is potential backing power, not an absolute guarantee. Its collateral value depends on a public risk rule.

For a notional N, define:

A simple rule would be:

A conservative rule would be:

An even more cautious version applies a haircut:

For the MVP, this document recommends: overcollateralization by sats enabled for display and limits; proof surplus displayed but haircut to zero until live risk rules are specified.

When E ≥N > 0, the backing exponent is:

Interpretation: semantic exponent coverage

1× to < 10× base / clean coverage

10× to < 100× superior backing power

100× to < 1000× strong collateral/proof surplus; eb ≥3: 1000× and above, specialized risk regime

An earlier conceptual error was to say that a loser "moves up in exponent". This phrasing is dangerous. In the v1 model, a loser enters deficit, degradation, dirty lineage, or lock. A winner or an overcollateralized UTXO gains a positive backing exponent.

Invariant 4 (Non-confusion). A positive exponent never automatically means debt.

Debt is not hidden inside eb; it is represented by a deficit_id, a state_class, and possibly a risk exponent.

A UTXO may contain a mixture of clean value and dirty fragments:

Component {
  component_id
  kind
  sats_atoms
  proof_atoms
  deficit_atoms
  claim_atoms
  position_id
  deficit_id
  ancestry_status
}

This representation avoids two symmetric errors: laundering debt by mixing, or contaminating an entire UTXO with a tiny dirty dust fragment.

When a transaction spends protocol inputs without an explicit allocation, Bitcoin does not say which sats go to which outputs. A historical analysis rule can distribute each component proportionally to the amounts of spendable outputs, excluding OP_RETURN and provably unspendable outputs. Fees receive no protocol state.

For remainders, use the largest-remainder method: 1. exact rational calculation; 2. floor for each output; 3. sort by largest remainder; 4. tie-break by ascending output index; 5. unit distribution of the remaining atoms.

Thus, the sum of child atoms equals the sum of parent atoms.

If an adversary sends 546 dirty sats to a clean wallet, and the wallet then merges them with 1 clean BTC, the output must become neither entirely clean nor entirely dirty. It must be mixed: almost all the value remains clean, but the dirty fragment persists and blocks its admission.

Invariant 5 (No laundering by complexity). No sequence of split, merge, dust, fee, covenant-like chain, or invalid allocation may transform dirty + complexity into clean + usable proof.

Component accounting is mathematically exact, but dangerous as a default live rule. An adversary can fragment a dirty position of 1 BTC into 100000 outputs of 1000 sats. If each output receives its own live debt object, the indexer preserves the debt but loses the state-growth war.

The v1 live rule is therefore: do not split live debt by default. Either the spender creates a valid bounded debt allocation, or the entire descendant lineage is blocked by a lineage lock referenced to the conserved deficit.

A debt carrier is an explicitly eligible UTXO carrying a deficit. For a deficit D and a carrier of S sats:

The allocation is valid only if:

The conservative v1 recommendation is MAX_DEBT_EXPONENT = 0, so S ≥D. A debt of 40000000 units cannot be pushed onto an output of 546 sats.

If a dirty or degraded position is spent without a valid bounded allocation, the indexer creates:

LineageLock {
  lock_id
  deficit_id
  root_spend_txid
  remaining_amount
  status
}

All descendants reference blocked_by = lock_id. This does not mean that every output owes the entire deficit. It means that it descends from unresolved debt and cannot be admitted as clean backing.

A lineage lock must not become a griefing weapon. Three recovery paths exist: 1. Full settlement. Anyone can pay the remaining deficit via the canonical route; if the deficit falls to zero, the lock is settled.

2. Explicit separation. A user who has merged clean value with locked value can separate the clean value from the blocked fragment without paying someone else's entire debt.

3. Bounded assumption. A user can create an eligible debt carrier that assumes the remaining deficit and converts the large lock into compact debt.

Invariant 6 (Anti-grief). Dirty dust does not block an address, a wallet, a person, or unrelated UTXOs. It blocks only protocol admission of outputs containing that lineage, and mixed clean value must be recoverable through valid separation.

A reservation asks the protocol to assign open claims to an open deficit:

"deficit":"DEFICIT_ID","amt":"400"} It is valid if the deficit exists, is open, belongs to the debtor actor, if the amount is positive and less than or equal to the open deficit, and if enough unassigned claim capacity exists.

The routing order must be deterministic. The prototype sorts by claim_id; the final version should favor Bitcoin evidence: block height, transaction index, OP_RETURN index, then txid.

A settlement is a Bitcoin transaction that pays the exact route outputs, in the assigned order, ignoring OP_RETURN outputs for matching:

"reservation":"RESERVATION_ID"} If the payment is accepted, the indexer:

Bitcoin does not need to understand claims. It proves that the sats were sent to the expected scripts. Pumpologia recognizes that proof as settlement.

The prototype uses a fixture-v0 oracle profile. Prices are indexed by profile and block height, as integers with an explicit scale. A missing price rejects the opening. For live operation, the specification must define:

This white paper proposes treating the oracle profile as part of Θ.

Changing the oracle, scale, or fallback changes the protocol and therefore must be versioned.

A fixture state root is:

The canonical input includes protocol id, version, block height, oracle profile id, actor balances, positions, carrier states, lineage edges, lineage locks, trades, PnL results, claims, deficits, settlement reservations, routes, assigned amounts, and payments. Maps are serialized as arrays sorted by stable identifier; outpoints as txid:vout; integers in decimal; no floats.

A rollback to height H is valid only if a checkpoint exists. The indexer restores all fields from the snapshot, truncates the event log, discards higher checkpoints, and returns the discarded events and the restored root. Rollback is control-plane, not a canonical protocol event.

Attack. A loser fragments a degraded carrier into thousands of dust outputs to force the indexer to track debt per output.

Defense. Without a valid bounded allocation, a single lineage lock is created. Descendants are blocked by the lock, but the debt remains a single object. Protocol admission is refused; live state remains bounded.

Attack. An adversary merges dirty value with clean value, then claims that the output is clean because the debt has been diluted.

Defense. The output becomes mixed or mixed locked. The clean value is not destroyed, but direct mint/trade is blocked. Explicit separation is required.

Attack. Send small dirty outputs to innocent users to contaminate their wallets.

Defense. The protocol blocks neither addresses, wallets, nor unrelated UTXOs. It blocks only outputs containing the lineage. Mixed clean sats can be recovered through separation.

Attack. Split a large debt into many outputs to make fractions disappear through rounding.

Defense. Proof atoms and deficit atoms are preserved. The largest-remainder method guarantees that child sums equal parent sums.

Attack. Publish an allocate or separate message that moves the debt to an output that is too small, declares dirty value as clean, or omits part of the deficit.

Defense. The allocation is accepted only if all inputs/outputs exist, conservation is exact, carrier thresholds are respected, and no dirty component becomes clean without settlement. Otherwise, lock or quarantine.

Attack. Exploit a missing price, an ambiguous scale, or a poorly specified limit condition.

Defense. The oracle profile is a versioned component of Θ. A transaction that requires a missing price is rejected or remains pending according to an explicit rule. Trigger comparisons use integers.

Attack. Two indexers diverge after a reorg because one retains events from an abandoned branch.

Defense. Checkpoints and rollback rules restore a complete state and truncate the event log. The state root provides proof of deterministic replay.

Pumpologia can evolve toward perps and futures because two forms of collateral power exist: 1. the sats present in UTXOs; 2. future sats represented by proof surplus and victory claims.

A derivative position can be represented as:

Position {
  actor_id
  backing_outpoint
  side: long | short
  instrument: spot | perp | future
  notional
  entry_oracle_price
  maintenance_rule
  proof_backing
  sats_backing
  effective_backing
  leverage_factor
  expiration_height? // futures
  funding_rule?      // perps
}

The difference from a custodial platform is decisive: Pumpologia does not need to seize BTC directly. Winners obtain surplus/claims; losers lose recognition and receive deficits, dirty lineage, or locks. Settlement reintroduces Bitcoin proof when payments are made.

Before going live, these markets require explicit rules:

The first live protocol should deliberately remain conservative:

The corpus identifies three critical deliverables before independent implementation: 1. proof-balances.md: availability, locked amounts, reserved amounts, actor-level versus UTXO-level proof.

2. upgrades.md: version activation, compatibility, deprecation, rereading old messages.

3. machine-readable test vector format, with the first complete Alice/Bob scenario.

The first test vector should fix the end-to-end semantics: 1. Alice creates 1000 $proof from 1000 sats, or directly opens a derivative position backed by 1000 sats.

2. Bob creates 1000 $proof from 1000 sats, or directly opens a symmetric position.

3. Alice opens a long.

4. Bob is on the losing side.

5. The oracle price moves in Alice’s favor.

6. Alice receives a claim of 400.

7. Bob falls to 600 of recognized capacity and 400 of deficit.

8. Bob reserves a settlement for 400.

9. Bob pays Alice via the assigned route.

10. Bob returns to clean capacity.

The vector must include transactions, blocks, oracle prices, messages, events, state roots, and expected rejection cases.

Traditional markets rely on intermediaries that keep the accounts, custody the assets, liquidate losers, and promise that the internal state is correct. Smart-contract protocols move part of this logic on-chain, at the cost of VM constraints, contractual attack surface, and often immobilized collateral.

Pumpologia proposes a third path: Bitcoin remains the registry of ownership and payment; market state is reconstructed publicly; the primary sanction is the loss of recognition.

This architecture is less spectacular than a contract that automatically seizes funds. It is also closer to the cypherpunk ethic: publish proofs, minimize trust, keep exit possible.

The vision is a market where accounts are not maintained by an institution, but by a replay function. A winner does not need a badge granted by an exchange: they possess a claim derived from history. A loser cannot be forced by Bitcoin to pay, but they cannot ask the protocol to forget. Clean capital remains clean; debt remains debt; complexity does not erase memory.

This white paper does not complete the specification. It sets the direction. The following points remain to be formalized:

Pumpologia is a simple proposition at its core: that Bitcoin history, read through public rules, can produce market state without a custodian. Transactions prove ownership and payments. Messages express intent. Oracles set prices.

Indexers derive claims, deficits, exponents, locks, and settlements. Recognition becomes a function, not a favor.

The promise is not that all losers will pay. No non-custodial protocol should lie about that limit. The promise is more robust: debt cannot be laundered through complexity, clean capital cannot be destroyed by dust griefing, and backing power can be measured without conflating victory, debt, and possession.

In a world where finance is often opaque by design, a system that turns public history into public state is already a break from the norm. If the final specs remain faithful to the invariants of conservation, boundedness, and deterministic replay, Pumpologia can become a Bitcoin-native market machine: austere, verifiable, implacable, and free.

// Fresh market open
{"p":"pumpologia","v":1,"op":"trade","action":"open",

"side":"long","out":0,"amt":"600","order":"market"}

// Limit open
{"p":"pumpologia","v":1,"op":"trade","action":"open",

"side":"long","out":0,"amt":"600","order":"limit", "limit_price":"65000","lock":"144"}

// Market close
{"p":"pumpologia","v":1,"op":"trade","action":"close",

"in":0,"out":0,"trade":"TRADE_ID","order":"market"}

// Limit close
{"p":"pumpologia","v":1,"op":"trade","action":"close",

"in":0,"out":0,"trade":"TRADE_ID","order":"limit", "limit_price":"70000","lock":"144"}

// Reservation
{"p":"pumpologia","v":1,"op":"reserve_settlement",

"deficit":"DEFICIT_ID","amt":"400"}

// Settlement
{"p":"pumpologia","v":1,"op":"settle",

"reservation":"RESERVATION_ID"}

// Recovery / bounded allocation sketch
{"p":"pumpologia","v":1,"op":"allocate","in":0,

"proof_outputs":[{"out":0,"proof":"60000000"}], "debt_outputs":[{"out":1,"deficit":"DEFICIT_ID", "amount":"40000000"}]}

Event Meaning POSITION_OPENED Fresh trade derives position and implicit mint.

MINT_ACCEPTED Prototype compatibility event for explicit mint.

TRADE_OPENED Trade accepted or pending according to order type.

TRADE_CLOSED Exit price fixed and trade closed.

PNL_COMPUTED Integer PnL computed from executed prices.

CLAIM_CREATED Positive PnL creates open claim.

DEFICIT_CREATED Negative PnL creates open deficit.

LINEAGE_DEGRADED Carrier or descendants marked dirty/degraded.

RESERVATION_CREATED Debtor requests canonical settlement route.

RESERVATION_ASSIGNED Claims assigned to route entries.

SETTLEMENT_PAID Bitcoin payment matches assigned route.

PROOF_BALANCE_CHANGED Recognized proof changes.

EXPONENT_CHANGED Backing or risk exponent recomputed.

LINEAGE_RESTORED Deficit reaches zero and lineage no longer fails admission.

1. OP_RETURN expresses intent, never spend authority.

2. Bitcoin inputs prove spend lineage.

3. Bitcoin outputs define carriers and payment evidence.

4. Protocol state never comes from wallet-local assumptions.

5. No trade spends more recognized proof than available.

6. No claim exists without winning PnL.

7. No deficit exists without losing PnL.

8. Every claim amount is matched by deficit amount under the chosen settlement model.

9. No reservation assigns already assigned or settled claim capacity.

10. No settlement restores capacity without exact route payment.

11. Debt is conserved until settlement.

12. Dirty or locked lineage cannot mint as clean by omission.

13. Clean value is not globally destroyed by dirty dust.

14. Tiny dirty outputs cannot carry usable positive proof.

15. Mixed outputs cannot trade directly under recommended v1 policy.

16. Debt carriers are bounded by exponent and count.

17. Lineage locks reference one deficit object, not one debt per descendant.

18. All consensus math is integer-only.

19. State roots serialize sorted stable identifiers, not process-local order.

20. Reorg rollback restores snapshots and truncates canonical event logs.

[1] Pumpologia Specs README. Protocol specification map, missing specs, invariants, and Alice/Bob test vector target. Internal draft, 2026.

[2] Pumpologia. Message Format Draft. Internal draft, 2026.

[3] Pumpologia. Minimal Transaction Model Draft. Internal draft, 2026.

[4] Pumpologia. Trading Draft. Internal draft, 2026.

[5] Pumpologia. Actor Resolution. Internal draft, 2026.

[6] Pumpologia. PnL Draft. Internal draft, 2026.

[7] Pumpologia. Claims Draft. Internal draft, 2026.

[8] Pumpologia. Deficits Draft. Internal draft, 2026.

[9] Pumpologia. Settlement Reservations Draft. Internal draft, 2026.

[10] Pumpologia. Settlement Payments Draft. Internal draft, 2026.

[11] Pumpologia. Exponent, Proof Collateral, Leverage, Perps, and Futures Specification Draft.

Internal draft, 2026.

[12] Pumpologia. Exponent State Accounting Specification Draft. Internal draft, 2026.

[13] Pumpologia. Taint Accounting Specification Draft. Internal draft, 2026.

[14] Pumpologia. Bounded Debt Carriers and Lineage Locks. Internal draft, 2026.

[15] Pumpologia. Lineage Lock Recovery Specification Draft. Internal draft, 2026.

[16] Pumpologia. Oracle Profile Draft. Internal draft, 2026.

[17] Pumpologia. State Root. Internal draft, 2026.

[18] Pumpologia. Reorg Rollback. Internal draft, 2026.

[19] Pumpologia. Bitcoin Transaction Templates and Exponent Systems Draft. Internal draft, 2026.