kripod / mental-poker Goto Github PK

View Code? Open in Web Editor NEW

69.0 7.0 16.0 1.53 MB

A purely functional mental poker library, based on the thesis of Choongmin Lee.

License: MIT License

JavaScript 100.00%

mental-poker poker crypto provably-fair

mental-poker's Introduction

mental-poker

A purely functional mental poker library, based on the thesis of Choongmin Lee.

Introduction

Mental poker makes it possible to play a fair game of poker over a physical distance without the need for a trusted third party, using cryptographic methods to shuffle and then deal from a deck of cards.

A coalition, even if it is of the maximum size, shall not gain advantage over honest players, except that players in a coalition may know the hands of each other.

Getting started

It is strongly recommended to read the specification before exploring the interface of the implementation.

An example of using the API can be found here.

Establishing a game

Configuration

Firstly, a configuration object has to be created and agreed upon by players.

import { createConfig } from 'mental-poker';

// Set up a game with a standard 52-card deck
const config = createConfig(52);

Initial deck setup

Each player shall generate a codeword fragment for each card of the configured deck type. Fragments which correspond to the same card will be combined to produce a deck of cards, represented as an array of codewords.

Players should share codeword fragments with each other through a commitment scheme, to prevent malicious entities from manipulating the generated codewords in their own favor.

import { createPlayer, createDeck } from 'mental-poker';

const self = createPlayer(config);

// Players should share their public data with each other
// Sensitive information (e.g. private keys) shall be kept in secret
const opponents = [
  /* Received from others */
];

// Points generation (Thesis, 3.1.1)
const cardCodewords = createDeck(
  [self, ...opponents].map(player => player.cardCodewordFragments),
);

After that, the deck shall be shuffled and each of its cards must be encrypted one by one.

import { encryptDeck, decryptDeck } from 'mental-poker';

// Any kind of array shuffling algorithm may be used
import shuffle from 'lodash.shuffle';

// The deck may also be received from the previous player in turn
let deck = cardCodewords;

// Cascaded shuffling (Thesis, 3.1.2)
// Each player shall shuffle the deck and encrypt it as a whole
deck = encryptDeck(shuffle(deck), self.keyPairs[config.cardCount].privateKey);

// The deck shall be passed on to the next player
deck = [
  /* And then received from someone else */
];

// Locking (Thesis, 3.1.3)
// Each player shall decrypt the deck as a whole and encrypt its cards one by one
deck = encryptDeck(
  decryptDeck(deck, self.keyPairs[config.cardCount].privateKey),
  self.keyPairs.map(keyPair => keyPair.privateKey),
);

Drawing cards

The value of a card may be known by anyone in possession of its corresponding private keys it has been encrypted with.

import { decryptCard } from 'mental-poker';

// Drawing/opening (Thesis, 3.2-3.3)
// Choose an encrypted card at random
const cardEncrypted = deck[i];

// Find out the codeword of the card after all the required keys are available
const cardDecrypted = decryptCard(
  cardEncrypted,
  [self, ...opponents].map(player => player.keyPairs[i].privateKey),
);

// The resulting codeword index below represents a card ID
// If its value is -1, then someone has violated the protocol
const codewordIndex = cardCodewords.findIndex(cardCodeword =>
  cardCodeword.equals(cardDecrypted),
);

API

Please see the API reference for further information.

mental-poker's People

Contributors

Stargazers

Watchers

Forkers

netzhuffle ottodevs mjmau denis-vilyuzhanin itoonx ruthraiahthulasi tearitco th3nolo imysun whitwaldo ichn-hu senior0909 juanumusic athiwatp mettaversesociety wighawag-bookmarks

mental-poker's Issues

Documentation

Kristóf, the implementation looks solid, however I can't find any documentation. The links in the README don't work anymore - I'm not sure what happened to the cypherpoker-js project.

Do you have copies of those docs that you can share? Thanks!

Dropout tolerance

Players may disconnect from the network during gameplay, and the game cannot be continued with missing player data. Dropout tolerance would allow any amount of players to disconnect without permamently interrupting the process of dealing new cards.

At first, this feature should be solved theoretically by extending the appendix of the API's specification.

Lee's protocol

Please note that Lee's simple cascaded shuffling and locking without any proof of correctness is insecure, if not all players follow the protocol instructions properly: A malicious player can replace some cards by undefined points (e.g. replace P_n by mG, for some random m), disturb the game, and will still remain undetected. This violates an important requirement of modern Mental Poker.

How do you run the example? Maybe a wiki would be helpful?

Figured this out / closing - to run the example use:

node --require babel-register index.js

Immutable design

Make most objects immutable and function-based.

Draft

Core methods

createPlayer({ id = getRandomId(), isSelf = false, points, secrets }): Creates a new Player with the fiven parameters. Auto-generates points and secrets if they are not set and isSelf is true.
createGame({ players, ...params }): Creates a new Game with the given array of players (minimum 2).
- Game#deckSequence: Represents the sequence of Decks used throughout the Game as an array.
- Game#cardsOfSelf: Represents the cards of self in order by an array of card IDs.
- Game#cardsOfCommunity: Represents the cards of the community in order by an array of card IDs.
- Game#unpickableCardIndexes: Keeps an ordered list of unpickable (owned or opened) card indexes.
- Game#getPickableCardIndexes(): Returns all card indexes which are not yet owned or opened by anyone.
- Game#getRandomPickableCardIndex(): Returns a random pickable card index.
- Game#getSecret(index): Returns a secret of self at the given index.
- Game#makeCardUnpickable(index): Marks a card at a given index unpickable, returning a new Game object.
- Game#drawCard(index, secretsOfOpponents): Draws a card for self at the given index, using the arrays of secrets for decryption, and making the card unpickable. Returns a new Game object with the picked card added to Game#cardsOfSelf.
- Game#openCard(index, secretsOfOpponents): Opens a card for the community at the given index, using the arrays of secrets for decryption, and making the card unpickable. Returns a new Game object with the picked card added to Game#cardsOfCommunity.
- Game#peekCard(index, secretsOfOpponents): Peeks at a card at the given index, using the arrays of secrets for decryption. Returns the ID of the peeked card.
- Game#verify(secretsOfOpponents): Verifies the entire game, looking for players who were not playing fairly. Returns the list of unfair players.
- Game#evaluateHands(unfairPlayers[, gameType = Config.gameType]): Evaluates the hands of players, looking for the winner(s) of the game, disqualifying unfair players. Returns the list of players who won the game.
createDeck(game): Creates a new Deck based on the given game.
- Deck#points: Represents the points of the Deck.
- Deck#encrypt([secret = game.secretsOfSelf[Config.cardsInDeck]]): Encrypts all of the Deck's points using a single secret.
- Deck#decrypt([secret = game.secretsOfSelf[Config.cardsInDeck]]): Decrypts all of the Deck's points using a single secret.
- Deck#shuffle(): Shuffles and encrypts the Deck using a single secret, returning a new Deck object.
- Deck#lock([secrets = game.secretsOfSelf]): Partially decrypts the Deck using a single secret, and then encrypts each point of it using multiple secrets, returning a new Deck object.
- Deck#unlockSingle(index, secretsOfOpponents): Decrypts a point of the Deck, returning the decrypted point.

Utility methods:

getRandomId(): Returns a random short ID.
getRandomPoints([amount = Config.cardsInDeck]): Returns an array of random points.
getRandomSecrets([amount = Config.cardsInDeck + 1]): Returns an array of random secrets.
shuffle(array): Shuffles an array using the Fisher-Yates algorithm as implemented by Durstenfeld, returning a new array.

Improve test suite parallelism

Lower the run time of tests and improve resource consumption.

Compatibility with secp256k1 4.0

secp256k1 4.0 removed privateKeyModInverse from the API, but has .privateKeyNegate, which can be used instead.

This has been discussed here and here.

Is it possible to update the code to use privateKeyNegate?

@kripod commented:

I’ve just finished working on the pull request and also clarified the difference between privateKeyNegate and privateKeyModInverse in the API docs.

But I can't find the PR or the docs.

NPM package

Hi @kripod,

I would like to use this repository within Node. I was wondering if you have wrapped this in an NPM package? If not, do you know how - or any pointers in the right direction?

I notice you use import which is ES6, whereas Node currently uses require.

Thanks in advance,
Will