CryptoCard.Core 1.0.0-alpha.1

CryptoCard

A cryptographically secure, provably fair .NET library for dealing generic card-like items to multiple parties.

Nobody sees a card they are not entitled to - the house included. There is no trusted dealer, no server that holds the deck, and no moment at which any single party knows the shuffle. The deck is shuffled by the participants together, each card is encrypted under a key no one holds alone, and a player's hole cards are readable by that player because every other participant published a decryption share for that slot and withheld their own.

Afterwards the whole hand is publicly verifiable, and verifying it reveals nothing that the players did not choose to reveal. A mucked hand is unrecoverable by anyone, forever.

Status: functionally complete, not yet externally reviewed. Every phase in docs/DESIGN.md §10 is built: the protocol state machine, the session API and hand archive, the offline verifier, two complete reference games (CryptoCard.Games.Holdem and CryptoCard.Games.DrawPoker, the latter exercising multi-batch dealing for games with a draw), a language-independent transcript specification, and an independent TypeScript reimplementation of the verifier. See Before real money below before using this for anything that matters.

How it works, briefly

CryptoCard implements Barnett-Smart mental poker over secp256k1: threshold ElGamal with zero-knowledge shuffle proofs.

The game publishes an initial ordering - an ordered list of whatever its cards are - and the cryptography deals only in slot indices. Decrypting a slot yields an index, which the game looks up in its own list. Your card type never touches the cryptography, so a 52-card deck, a 53-card joker deck, a 312-card six-deck shoe and a Uno deck are all the same problem, and duplicates need no special handling at all.

Round trips are the constraint that shapes the rest. Decks are shuffled during the previous hand, each participant sends exactly one batched message to deal the table, and betting and streets cost no network round trips at all.

See docs/DESIGN.md for the protocol, the threat model, what is deliberately not defended against, and the performance budget.

Documentation

New to CryptoCard? Start with the guide - a multi-page walkthrough from a first hand through writing your own game, with runnable examples. Everything else is a reference for once you know roughly what you're looking for:

• docs/guide/ - tutorial: identities, sessions, dealing, archives, writing a game.
• docs/API.md - the complete public surface as a shape reference.
• docs/DESIGN.md - the specification: protocol, threat model, performance.
• docs/TRANSCRIPT-SPEC.md - the wire format and verification algorithm, specified independently of this repository's own code.
• docs/REPOSITORY.md - repository layout and build conventions.
• docs/LEDGER-DESIGN.md - the CryptoCard Ledger: a signed, replay-verified record of a table's deposits, wagers and payouts, signed by the same identities that sign the cards (CryptoCard.Ledger, CryptoCard.Ledger.Verify).
• docs/SUPPLY-CHAIN.md - which supply-chain controls are on, which are not, and what each is waiting for.
• src/CryptoCard.Table/ - optional: the hands and the ledger replayed together, one timeline per hand of cards and chips under the same identities.
• arduino/CryptoCardEmbedded/ - a C++ port of the participant role for an ESP32-P4 player terminal, in progress.

Building

Open CryptoCard.sln in Visual Studio, or:

dotnet build CryptoCard.sln
dotnet test CryptoCard.sln

The libraries target netstandard2.0 and net10.0. global.json rolls forward, so any SDK from 10.0.100 upwards works without editing anything.

Before real money

docs/DESIGN.md §10 makes external review of the protocol and of CryptoCard.Math a precondition, and that has not happened. A provably-fair library that nobody outside the project has examined is asking for exactly the trust it claims to remove.

Licence

AGPL-3.0-or-later. See LICENSE.