Overview
A Probabilistic Transaction (PTX) is an extension of the existing `CTransaction` that encodes a list of possible outputs and the probability range associated with each. When the PTX is included in a block, the network uses the block’s Gamemaster VRF (verifiable random function) output and the transaction’s ID to derive a random number. That number determines the winning output; the other outputs are ignored. The mechanism works at consensus, so the game outcome does not depend on off‑chain secrets or an external oracle.
The design touches several areas of the Hemis codebase:
1. Transaction structures and serialization (`src/primitives/transaction.h/cpp`).
2. Consensus and mempool rules (`src/consensus/tx_verify.cpp`, `src/validation.cpp`, `src/txmempool.cpp`).
3. Gamemaster VRF plumbing (`src/llmq`).
4. Wallet creation and RPC (`src/wallet`, `src/rpc`).
5. UI support (`src/qt`).
1 Transaction format
A new structure `CProbabilisticTransaction` inherits from `CTransaction` and adds:
- `std::vector<RangeOutput> vRanges`: each entry contains a `CTxOut` and an inclusive probability interval (`rangestart`/`rangeend`) over a fixed range (e.g. 0–65 535 for a 16‑bit RNG). The sum of ranges must cover the entire space.
- `uint32_t nSeedHeight`: the block height whose VRF will be used. Committing to a future block prevents miners from manipulating randomness.
- `uint32_t nExpiryHeight`: last height at which the PTX is valid; helps bound mempool life.
Serialization functions must be updated to handle these fields, and `CTransaction::nVersion` or a custom flag identifies PTXs.
2 Consensus validation
- During block validation (`src/validation.cpp`), if a transaction is flagged as PTX, the node calls `CheckProbabilisticTx`.
- `CheckProbabilisticTx` obtains the VRF output for `nSeedHeight` via `llmq::GetVrfForHeight`. It computes a 32‑bit integer `r = Truncate32(Hash(ptx.GetHash(), vrf))`. The node locates the `RangeOutput` whose interval contains `r` and asserts that the PTX’s outputs in the block match exactly the chosen range’s `CTxOut` plus any Gamemaster fee output.
- The function also enforces that `nSeedHeight >= currentheight` and `currentheight <= nExpiryHeight` to prevent expired bets.
- Additional rules limit house edge (e.g. ≤1 %) and check that the sum of outputs does not exceed the inputs minus fees.
3 Gamemaster VRF integration
The existing LLMQ (Gamemaster) code already produces VRF values for quorum selection. We extend this by:
- Storing the final VRF value in each block header or a dedicated field within `CBlockIndex` (e.g. `nVrfOutput`).
- Exposing a function `uint32_t GetVrfForHeight(int height)` in `llmq` to retrieve the VRF for a given block height.
- Ensuring that the VRF output for a given height is available before miners know which PTXs will be included, preventing them from selectively mining only winning transactions.
4 Mempool policies
Mempool logic (`src/txmempool.cpp`, `src/policy/`) must enforce that:
- `nSeedHeight` is not in the past and not too far in the future (e.g. within 10 blocks).
- `nExpiryHeight` > `nSeedHeight` and not too distant.
- The range intervals are contiguous and cover the entire range (0–MAX_RANGE).
PTXs that violate these rules are rejected before reaching consensus validation.
5 Wallet and RPC
Changes to `src/wallet/wallet.cpp` and `src/rpc/rawtransaction.cpp` include:
- A new RPC method `createrangebet` that accepts a list of destination addresses and weights, optional house edge, seed height and expiry. It builds a `CProbabilisticTransaction`, splitting the stake according to weights and encoding contiguous ranges.
- The wallet UI shows a “Play Game” dialog where the user enters stake and opponent; the app constructs the PTX, signs it with one click and broadcasts.
6 Activation and governance
Implementing PTX is a consensus change. Hemis should wrap it behind a version bit (similar to Dash spork or BIP9) and require a super‑majority of Gamemasters and masternodes to signal readiness before enforcing PTX rules. This avoids accidental chain splits and allows for community review and external audit.
