398b5fe2-da27-4772-81ce-37fa615719b5.xml (12, 2017-07-07)
BitPoker Start Game Sequence.xml (855, 2017-07-07)
BitPoker.AI/ (0, 2017-07-07)
BitPoker.AI/BitPoker.AI.csproj (1811, 2017-07-07)
BitPoker.AI/CallingStation.cs (374, 2017-07-07)
BitPoker.AI/Properties/ (0, 2017-07-07)
BitPoker.AI/Properties/AssemblyInfo.cs (990, 2017-07-07)
BitPoker.API.WebTests/ (0, 2017-07-07)
BitPoker.API.WebTests/BitPoker.API.WebTests.csproj (4112, 2017-07-07)
BitPoker.API.WebTests/Players.webtest (1586, 2017-07-07)
BitPoker.API.WebTests/Properties/ (0, 2017-07-07)
BitPoker.API.WebTests/Properties/AssemblyInfo.cs (1378, 2017-07-07)
BitPoker.API.WebTests/Tables.webtest (1497, 2017-07-07)
BitPoker.API/ (0, 2017-07-07)
BitPoker.API/Web.config (2476, 2017-07-07)
BitPoker.Clients.JSONRPC/ (0, 2017-07-07)
BitPoker.Clients.JSONRPC/BaseClient.cs (1149, 2017-07-07)
BitPoker.Clients.JSONRPC/BitPoker.Clients.JSONRPC.csproj (3163, 2017-07-07)
BitPoker.Clients.JSONRPC/PeerClient.cs (1157, 2017-07-07)
BitPoker.Clients.JSONRPC/Properties/ (0, 2017-07-07)
BitPoker.Clients.JSONRPC/Properties/AssemblyInfo.cs (1424, 2017-07-07)
BitPoker.Clients.JSONRPC/TableClient.cs (2487, 2017-07-07)
BitPoker.Clients.JSONRPC/packages.config (141, 2017-07-07)
BitPoker.Clients.Mocks/ (0, 2017-07-07)
BitPoker.Clients.Mocks/BitPoker.Clients.Mocks.csproj (2904, 2017-07-07)
BitPoker.Clients.Mocks/PeerClient.cs (721, 2017-07-07)
BitPoker.Clients.Mocks/Properties/ (0, 2017-07-07)
BitPoker.Clients.Mocks/Properties/AssemblyInfo.cs (1420, 2017-07-07)
BitPoker.Clients.Mocks/UserAgentClient.cs (433, 2017-07-07)
BitPoker.Clients.Rest/ (0, 2017-07-07)
BitPoker.Clients.Rest/BitPoker.Clients.Rest.csproj (4391, 2017-07-07)
BitPoker.Clients.Rest/Client.cs (3202, 2017-07-07)
BitPoker.Clients.Rest/Properties/ (0, 2017-07-07)
BitPoker.Clients.Rest/Properties/AssemblyInfo.cs (1418, 2017-07-07)
BitPoker.Clients.Rest/packages.config (140, 2017-07-07)
BitPoker.Clients.ZeroMQ/ (0, 2017-07-07)
BitPoker.Clients.ZeroMQ/BitPoker.Clients.ZeroMQ.csproj (4287, 2017-07-07)
BitPoker.Clients.ZeroMQ/Client.cs (2228, 2017-07-07)
BitPoker.Clients.ZeroMQ/Properties/ (0, 2017-07-07)
... ...
# BitPoker.IO
## Abstract
Inspired by OpenBazaar.com, the goal of the project is to design a peer to peer protocol of turn based games, such as online poker, in which no central actor can control the outcome and thus rig the game and is provably fair. The game uses bitcoin (or other digital tokens) and lightning network to settle bets between actors, and a blockchain to persist the state of the game.
Most blockchains are too slow for turned based games, but not all turns need to persisted back to the blockchain. For example, in poker, turns can be stored in memory on clients as "mini chains". Only when the outcome of the game is required such as awarding the pot, is the data required to be persisted back to the blockchain. Furthermore, players could agree this could be a higher cadence, such as each orbit, to save on fees.
Its hoped, that different clients developed in different programming languages will be built.
### Notation & Conventions
Ids should be represented as GUIDs, and be in lower case
All values represented in base16 (hex) should be lower case
Bitcoin addresses are used the the player identifier
Time stamps are EPOCH
Time durations are in seconds
Amounts should be in smallest crytocurrency unit, such as Satoshis for Bitcoin
### Enumerations
Deck is represented as an array of bytes.
| Key | Value | Decimal | Byte |
| -----|------ | --------|----- |
| A | Ace | 12 | {0x0C} |
| K | King | 11 |{0x0B}|
| Q | Queen | 10 |{0x0A}|
| J | Jack | 9 |{0x09}|
| T | Ten | 8 |{0x08}|
| 9 | 9 | 7 |{0x07}|
| 8 | 8 | 6 |{0x06}|
| 7 | 7 | 5 |{0x05}|
| 6 | 6 | 4 |{0x04}|
| 5 | 5 | 3 |{0x03}|
| 4 | 4 | 2 |{0x02}|
| 3 | 3 | 1 |{0x01}|
| 2 | 2 | 0 |{0x00}|
Suites
| Key | Value | Offset | Byte |
| ---- | ----- | ------ | ---- |
| S | Spade | +0 | {0x00} |
| C | Club | +13 | {0x0D} |
| H | Heart | +26 | {0x1A} |
| D | Diamond | +39 | {0x27} |
\*Eg
Ace of clubs = { 0x0D }
Crypto Currencies
BTC Bitcoin
ETH Ethereum
ETC Ethereum Classic
### Poker terminology
- SB = Small Blind
- BB = Big Blind
### Example Keys (Address, Public Key (Not compressed), WIF Private Key)
*Alice*
- msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv
- 041FA97EFD760F26E93E91E29FDDF3DDDDD3F543841CF9435BDC156FB73854F4BF22557798BA535A3EE89A62238C5AFC7F8BF1FA0985DC4E1A06C25209BAB78BD1
- 93Loqe8T3Qn3fCc87AiJHYHJfFFMLy6YuMpXzffyFsiodmAMCZS
*Bob*
- mhSW3EUNoVkD1ZQV1ZpnxdRMBjo648enyo
- 04F48396AC675B97EEB54E57554827CC2B937C2DAE285A9198F9582B15C920D91309BC567858DC63357BCD5D24FD8C041CA55DE8BAE62C7315B0BA66FE5F96C20D
- 91yMBYURGqd38spSA1ydY6UjqWiyD1SBGJDuqPPfRWcpG53T672
*Witness*
- mq1Ctw6xTcomjGgQz5pi8oXdR1tjjZQHYs
- 04C82B8E2D6EA7F17665C4A1070F340E84D4C02DA72AE5018574001841C10E8009A04E2C333D3EB90102E71B324BFE595430D4C654BBFF0F66EDBFE63798C7A271
- 93C4fbYtv8VXWDnbJLzQiVfBGuQgfz1hBF1QwQeJxQepe9oE876
\*2 of 3 address
2NCSTuV27SC1BF122Xe1wmkNkjo4MJw4W85
https://testnet.blockexplorer.com/address/2NCSTuV27SC1BF122Xe1wmkNkjo4MJw4W85
*Redeem Script* 524104c82b8e2d6ea7f17665c4a1070f340e84d4c02da72ae5018574001841c10e8009a04e2c333d3eb90102e71b324bfe595430d4c654bbff0f66edbfe63798c7a2714104f48396ac675b97eeb54e57554827cc2b937c2dae285a9198f9582b15c920d91309bc567858dc63357bcd5d24fd8c041ca55de8bae62c7315b0ba66fe5f96c20d4104f48396ac675b97eeb54e57554827cc2b937c2dae285a9198f9582b15c920d91309bc567858dc63357bcd5d24fd8c041ca55de8bae62c7315b0ba66fe5f96c20d53ae
\*2 of 2 address
2MtFGSjUn1FLhwgyf7gAaX3n1wCg29B4wvh
*Redeem Script*
5241041fa97efd760f26e93e91e29fddf3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba535a3ee89a62238c5afc7f8bf1fa0985dc4e1a06c25209bab78bd14104f48396ac675b97eeb54e57554827cc2b937c2dae285a9198f9582b15c920d91309bc567858dc63357bcd5d24fd8c041ca55de8bae62c7315b0ba66fe5f96c20d52ae
Created from http://ms-brainwallet.org
https://coinb.in/?verify=524104c82b8e2d6ea7f17665c4a1070f340e84d4c02da72ae5018574001841c10e8009a04e2c333d3eb90102e71b324bfe595430d4c654bbff0f66edbfe63798c7a2714104f48396ac675b97eeb54e57554827cc2b937c2dae285a9198f9582b15c920d91309bc567858dc63357bcd5d24fd8c041ca55de8bae62c7315b0ba66fe5f96c20d4104f48396ac675b97eeb54e57554827cc2b937c2dae285a9198f9582b15c920d91309bc567858dc63357bcd5d24fd8c041ca55de8bae62c7315b0ba66fe5f96c20d53ae#verify
## The protocol
Each client connects to one another in the "lobby". They can then look for players who are looking to start a game, or request to join a running game. Messages are sent to all players, signed, and referencing the existing message. Thus like a block chain of messages.
- Table reaches consensus on who’s turn to act based off the game contract
- Table reaches consensus on the legal moves / actions a player can make
- Table waits for a signed message from that player
- All other players validate that message
- Repeat
### Valid methods (See below for sample messages)
Methods are of two types. Game play / action messages that determin a players turn intent. Methods that do not, such as join a table.
Non action methods
- Join
- BuyIn
- Deal
- Quit
- SitOut
- Shuffle
- Leave
Action methods
- SmallBlind
- BigBlind
- Call
- Bet
- Raise
- Fold
- Muck
### Overview
If the game is to be developed using Ethereum contracts:
1. The game is defined as an Ethereum contract
2. Players agree to the table contract
3. Each players actions are defined as inputs for the hand contract
4. After the hand has ended, each player verifies the integrity of the hand contract. Its in everyones best interest to verify correctly [Game Theory Citation]
5. The hand message chain is then executed on the Ethereum network for the pot to be awarded
Less use of Ethereum
1. Players connect to each other via a P2P network protocol.
2. A player either looks to join a table and reviews the contract.
3. A player can choose to start a table be defining a table contract.
4. Tables should also broad cast their game, status and number of current .players to other tables for better network propagation.
5. Leaving the table (closing the channel)
6. Lightning network will facilitate micro payments "off chain". The table can agree to bring them "on chain" after n hands are dealt.
### Aside: Lightning Network
*How it Works.*
Funds are placed into a two-party, multi signature "channel" bitcoin address. This channel is represented as an entry on the bitcoin public ledger. In order to spend funds from the channel, both parties must agree on the new balance. The current balance is stored as the most recent transaction signed by both parties, spending from the channel address. To make a payment, both parties sign a new exit transaction spending from the channel address. All old exit transactions are invalidated by doing so.
The Lightning Network does not require cooperation from the counterparty to exit the channel. Both parties have the option to unilaterally close the channel, ending their relationship. Since all parties have multiple multi signature channels with many different users on this network, one can send a payment to any other party across this network.
By embedding the payment conditional upon knowledge of a secure cryptographic hash, payments can be made across a network of channels without the need for any party to have unilateral custodial ownership of funds. The Lightning Network enables what was previously not possible with trusted financial systems vulnerable to monopolies—without the need for custodial trust and ownership, participation on the network can be dynamic and open for all.
[https://lightning.network/lightning-network-summary.pdf]
## Game as a contract
In the below *table contract* the below game Texas Holdem is defined as an Enum. The whole rules of the game could be defined as a contract, thus allowing anyone to develop variations of the game, such as the "Seven Duce" rule, other variations of poker such as Omaha or even other games.
These are out side the scope of this paper.
Ropsten keys (in folder)
MyEtherWallet password Test12345
Private Key bbbe14b22e95f7d48a1b1268d27440078fdfd29183d00102319a61b3ba5b8511
Account 0x736060769FfE0fFB6e1799A06B2F5633ABAb53E0
## Messages
All actions are sent as JSON RPC. They must include a public key hash and be signed. The payload must also reference their previous message hash.
1. Concatenate the payload the values
2. Hash the payload of step 1
3. Sign the output of step 2
General message object as a JSON RPC param
| Property | Eg |
| -------- | -- |
| Version | Message Version |
| Id | GUID |
| Bitcoin Address (Public Key Hash) | msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv |
| Method | Enum (TABLE, ACTION, BUYIN, SHUFFLE, DECK) |
| Payload Hash | SHA256 |
| Message Signature | TODO |
| Pervious Hash | TODO |
Example action message (payload)
| Property | Eg |
| --------- | -- |
| Id | 47b466e4-c852-49f3-9a6d-5e59c62a98b6 |
| Bitcoin Address (Public Key Hash) | msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv |
| Index | 2 |
| Action | CALL 5000000 |
| TX | TODO |
| Previous Hash | TODO |
| Time stamp | 2016-08-17 00:00:00 |
Eg in Json
```
{"TableId":"bf368921-346a-42d8-9cb8-621f9cad5e16","HandId":"398b5fe2-da27-4772-81ce-37fa615719b5","Index":2,"Action":"CALL","Amount":5000000,"Tx":null,"PreviousHash":"8ab9f91c002d8ccdbd8a49f7e028d27ca6ef01cf1fdaa4eca637868d8e4adf31","HashAlgorithm":"SHA256","Version":1.0,"BitcoinAddress":"msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv","TimeStamp":"2016-08-17T00:00:00"}
```
SHA-256 hash of the JSON RPC method
```
cb19bc14bca61bee174e5d6591530ad72b3ab58e0c5a904baec5b5de85c65e88
```
## Sample messages
### Buy In
```
```
### Call
```
```
## Adding a Table Contract
A client will define the table contract and store that locally. They become the table starter and thus define the conditions of that game. The parameters for a table are defined in the following schema. Developers are encouraged to create their own algorithms, such as voting or anti-collusion.
1. Encryption Algorithm (Enum AES-256)
2. Hash Algorithm (Enum SHA-256)
3. Id (GUID)
3. Currency (Enum)
3. Blinds
4. Rake\*
5. Min players
6. Max players
7. Game type (Enum, No Limit Texas Holdem) \*
8. Other (straddles, "run it twice") \*
9. Channel Address / multisig
10. Consensus Algorithm
11. Anti Collusion Algorithm / Contract
12. Version
13. Voting Algorithm / Contract
14. Channel Address
* Perhaps an entire contract
*Example xml serialziation*
```
AES-265
SHA-256
BTC
100000
200000
10000000
50000000
Texas Holdem
No Limit
30
120
0.0.1
```
```
{
table : {
id : "bf368921-346a-42d8-9cb8-621f9cad5e16"
encryption : "AES-256",
hash : "SHA-256",
currency : "BTC",
blinds : {
small : 100000,
big : 200000
},
buyIn : {
min : 10000000
max : 50000000
}
}
}
```
## Joining a Table
Users send their intent to join a table by the JoinTable method. This is analogous choosing a seat and sitting down at the table. Once the table reaches the maximum amount of players, or the players vote to start the table, a multi signature address is created. The required signatures are part of the agreed table contract.
```
{
method : "JoinTable",
version : 1
params {
publicKey : "04F48396AC675B97EEB54E57554827CC2B937C2DAE285A9198F9582B15C920D91309BC567858DC63357BCD5D24FD8C041CA55DE8BAE62C7315B0BA66FE5F96C20D",
minStart : 2
}
}
```
Response
```
```
## Buying in
All players buying in open a lightning payment channel with the multi signature address of the table. Players must add BTC within the range for the table contract (MinBuyIn, MaxBuyIn)
"Through this network of interconnected payment channels, Lightning provides a scalable, decentralised micropayments solution on top of the Bitcoin blockchain." [https://lightning.network/lightning-network-technical-summary.pdf]
## Witness nodes
Game witness can also be allowed or chosen to arbitrate a game. The witness could also help network propagation. A witness would be choose by the table starter and a small rake paid to the witness.
There might become a market for reputable witnesses based off a HTTPS DNS endpoint and earn small revenues for witnessing hands.
### Process
1. Alice and Bob create a 2 of 2 address
2. Alice creates a deposit transaction
3. Bob creates a deposit transaction
4. Alice creates a refund transaction but does not broadcast
5. Bob creates a refund transaction but does not broadcast
\*2 of 2 Redeem Script and Address for Alice and Bob
```
2 041fa97efd760f26e93e91e29fddf3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba53
5a3ee89a62238c5afc7f8bf1fa0985dc4e1a06c25209bab78bd1 041fa97efd760f26e93e91e29fd
df3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba535a3ee89a62238c5afc7f8bf1fa098
5dc4e1a06c25209bab78bd1 2 OP_CHECKMULTISIG
2Mx377XSXhvqqVyLaXsPDAAEsJFzGeWunKi
```
### Funding TXs
Both Alice and Bob now deposit their buy in to the address 2Mx377XSXhvqqVyLaXsPDAAEsJFzGeWunKi. Note: The table contract could include a minimum confirmation count.
Alice tx f5c5e008f0cb9fc52487deb7531a8019e2d78c51c3c40e53a45248e0712102a3
Bob tx c60193a33174a1252df9deb522bac3e5532e0c756d053e4ac9999ca17a79c74e
\*Sample C# NBitcoin code
```
const String alice_wif = "93Loqe8T3Qn3fCc87AiJHYHJfFFMLy6YuMpXzffyFsiodmAMCZS";
NBitcoin.BitcoinSecret alice_secret = new NBitcoin.BitcoinSecret (alice_wif, NBitcoin.Network.TestNet);
NBitcoin.BitcoinAddress alice = alice_secret.GetAddress ();
//Create 2 of 2
NBitcoin.Script table = NBitcoin.PayToMultiSigTemplate
.Instance
.GenerateScriptPubKey(2, new[] { alice_secret.PubKey, alice_secret.PubKey });
Console.WriteLine(table);
Console.WriteLine(table.Hash.GetAddress(NBitcoin.Network.TestNet));
NBitcoin.IDestination msigAddress = table.Hash.GetAddress(NBitcoin.Network.TestNet);
var blockr = new NBitcoin.BlockrTransactionRepository(NBitcoin.Network.TestNet);
NBitcoin.Transaction transaction = blockr.GetAsync(new NBitcoin.uint256("f5c5e008f0cb9fc52487deb7531a8019e2d78c51c3c40e53a45248e0712102a3")).Result;
NBitcoin.Coin[] aliceCoins = transaction
.Outputs
.Select((o, i) => new NBitcoin.Coin(new NBitcoin.OutPoint(transaction.GetHash(), i), o))
.ToArray();
var txBuilder = new NBitcoin.TransactionBuilder();
var tx = txBuilder
.AddKeys(alice_secret.PrivateKey)
.AddCoins(aliceCoins)
.Send(msigAddress, new NBitcoin.Money(50000000))
.SetChange(alice)
.SendFees(NBitcoin.Money.Coins(0.001m))
.BuildTransaction(true);
Boolean ok = txBuilder.Verify(tx);
Console.WriteLine(tx.ToHex());
```
\*Raw TX Alice buy in of 0.5 BTC
```
0100000001a3022171e04852a4530ec4c3518cd7e219801a53b7de8724c59fcbf008e0c5f5000000
008b483045022100c21e5c296d3024f64dbd948b1999933206a3d3d757ff1004ce874fa4b9277acc
02202d0c0115b4f52a7de2a1863141eda25192255015da14765a1409d8d202f096b40141041fa97e
fd760f26e93e91e29fddf3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba535a3ee89a62
238c5afc7f8bf1fa0985dc4e1a06c25209bab78bd1ffffffff02e069f902000000001976a914822f
3782f8d0357cb6fc7b4c5cfc1424b3f0100988ac80f0fa020000000017a914348de5f6c91078c128
4956a88a9322be8d2834148700000000
```
\*In JSON
```
{
"txid": "0e7ae471ffd578c64b142c232f36c3f7810e1fcb2e31b8c1b02f4c61c07859dc",
"size": 256,
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "f5c5e008f0cb9fc52487deb7531a8019e2d78c51c3c40e53a45248e0712102a3",
"vout": 0,
"scriptSig": {
"asm": "3045022100c21e5c296d3024f64dbd948b1999933206a3d3d757ff1004ce874fa4b9277acc02202d0c0115b4f52a7de2a1863141eda25192255015da14765a1409d8d202f096b4[ALL] 041fa97efd760f26e93e91e29fddf3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba535a3ee89a62238c5afc7f8bf1fa0985dc4e1a06c25209bab78bd1",
"hex": "483045022100c21e5c296d3024f64dbd948b1999933206a3d3d757ff1004ce874fa4b9277acc02202d0c0115b4f52a7de2a1863141eda25192255015da14765a1409d8d202f096b40141041fa97efd760f26e93e91e29fddf3ddddd3f543841cf9435bdc156fb73854f4bf22557798ba535a3ee89a62238c5afc7f8bf1fa0985dc4e1a06c25209bab78bd1"
},
"sequence": 4294967295
}
],
"vout": [
{
"value": 0.499,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 822f3782f8d0357cb6fc7b4c5cfc1424b3f01009 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914822f3782f8d0357cb6fc7b4c5cfc1424b3f0100988ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv"
]
}
},
{
"value": 0.5,
"n": 1,
"scriptPubKey": {
"asm": "OP_HASH160 348de5f6c91078c1284956a88a9322be8d283414 OP_EQUAL",
"hex": "a914348de5f6c91078c1284956a88a9322be8d28341487",
"reqSigs": 1,
"type": "scripthash",
"addresses": [
"2Mx377XSXhvqqVyLaXsPDAAEsJFzGeWunKi"
]
}
}
]
}
```
Which yields transaction id 0e7ae471ffd578c64b142c232f36c3f7810e1fcb2e31b8c1b02f4c61c07859dc
Bobs transaction id d74b4bfc99dd46adb7c30877cc3ce7ea13feb51a6fab3b9b15f75f4e213ac0da
The address 2Mx377XSXhvqqVyLaXsPDAAEsJFzGeWunKi now contains 1btc https://testnet.blockexplorer.com/address/2Mx377XSXhvqqVyLaXsPDAAEsJFzGeWunKi
*Sample opening lightning channel in c# / NBitcoin*
```
TODO
```
### Create the refund transaction
Alice and Bob must also create a refund transaction to themselves, but *not* broadcast it.
## Game play
The dealer's client is responsible for the orchestration of the game. As the dealer position rotates, this isn't a centralisation risk. The intent is to limit network traffic.
1. Define the hand contract
2. Shuffle the deck
3. Post blinds
4. Pre flop round
5. Deal the flop
6. Post flop round
7. Deal the turn
8. Post turn round
9. Deal the river
10. Post river round
11. Award the pot
### Hand Contract
At the start of each hand, the dealer defines the hand contract which references the table contract.
1. The players and seat positions
2. The stack of each player
3. A ID as a GUID
\*Example hand contract serialised in XML Download from test data folder
```
1
47b466e4-c852-49f3-9a6d-5e59c62a98b6
msPJhg9GPzMN6twknwmSQvrUKZbZnk51Tv
HEVF2mU1K0MmgeaP/zlxjCDkgbz43I638QaWwM/ipcrfWbSZwfx96MDxcqDr3dTBzzKMr9EnNqBjJlIQLk6Tdmg=
2016-08-17T00:00:00
bf368921-346a-42d8-9cb8-621f9cad5e16
398b5fe2-da27-4772-81ce-37fa615719b5
0
SMALL BLIND
50000
SHA256
1
a29bc370-9492-4b60-ad4f-7c7513064383
mhSW3EUNoVkD1ZQV1ZpnxdRMBjo648enyo
HATytRG1kIsPUVxELt7/m40EwCn4ryaV2p6Xmr38rijmAsm3pra8vv ... ...