Documentation

Understanding SparkBet's provably fair gaming protocol

Commit-Reveal Protocol

How we ensure provably fair outcomes

1. Commitment Phase

When you create a game, you choose "heads" or "tails". Your choice is combined with a random 32-byte nonce and hashed using SHA256. Only this hash is submitted to the blockchain, making your actual choice cryptographically hidden.

commit_hash = SHA256(choice + ":" + nonce)

2. Opponent Joins

Your opponent joins the game and can see your commit hash but cannot determine your actual choice. They make their own choice and commit it the same way.

3. Reveal Phase

Both players reveal their choice and nonce. The smart contract verifies that each revealed choice matches the original commit hash. If they match, the winner is determined. If either player tries to cheat by changing their choice, the hash won't match and they forfeit.

Why this works: It's cryptographically impossible to find a different choice + nonce combination that produces the same hash. Once committed, you cannot change your decision.

PSBT Multisig Escrow

Trustless fund management

When both players join a game, their bet amounts are locked in a 2-of-2 multisig address using Partially Signed Bitcoin Transactions (PSBTs). This means:

  • •Both signatures required: Neither player can unilaterally take the funds
  • •CLTV refund path: Includes a CheckLockTimeVerify (CLTV) timeout that allows refunds if game doesn't complete
  • •Cooperative payout: After reveals are verified, both players sign a payout transaction to the winner

Escrow Flow:

  1. 1. Create PSBT with 2-of-2 multisig output + CLTV refund branch
  2. 2. Player 1 signs PSBT → Player 2 signs PSBT
  3. 3. Broadcast fully signed PSBT to lock funds
  4. 4. After reveals verified → Create payout PSBT to winner
  5. 5. Both players sign payout → Winner receives funds

Timeout & Dispute Resolution

Your funds are never stuck

SparkBet includes multiple timeout mechanisms to ensure your funds are never permanently locked:

Commit Timeout (5 minutes)

If opponent doesn't join within 5 minutes, game expires and creator can reclaim their commit.

Reveal Timeout (5 minutes)

If a player doesn't reveal within 5 minutes after both commits, they forfeit and the other player wins.

CLTV Refund (~24 hours)

If cooperative payout fails, after ~144 blocks (~24 hours) either player can claim refund via the CLTV-locked path in the escrow.

Security Considerations

Important information before playing

•Never reuse nonces: Each game generates a fresh random nonce. Reusing nonces can compromise security.
•Verify independently: All commits and reveals are on-chain. You can verify any game result independently.
•Testnet first: Always test on testnet before using mainnet with real funds.
•Audit required: Smart contracts and PSBT logic require professional security audit before mainnet launch.