SDK

Everything the client ships with

packages/sdk wraps CardEntropy's ABI, turns card ids into something readable, and does the same hash-chain math the keeper runs.

Usage

usage.ts

import { createPublicClient, createWalletClient, http } from "viem";
import { CardProtocolClient, decodeCards, generateHashChain } from "@card-protocol/sdk";

const publicClient = createPublicClient({ transport: http(RPC_URL) });
const walletClient = createWalletClient({ account, transport: http(RPC_URL) });

const client = new CardProtocolClient({ cardEntropyAddress, publicClient, walletClient });

// Request 5 cards
const { sequenceNumber } = await client.requestDraw({ provider: dealer, numCards: 5, account });

// Wait for the reveal and decode the result
const { cards } = await client.waitForReveal(sequenceNumber);
console.log(cards.map((c) => c.label)); // e.g. ["K♠", "4♥", "9♦", "A♣", "10♥"]

CardProtocolClient

Reads & writes against CardEntropy

getFee(provider)

Reads a provider's current per-request fee, in wei.

requestDraw({ provider, numCards, account, userRandom?, gasLimit? })

Sends the request transaction and returns its sequenceNumber once mined.

requestShuffle({ provider, account })

Sugar for requestDraw(..., numCards: 52) - a full-deck shuffle.

waitForReveal(sequenceNumber)

Watches for the Revealed event and resolves with decoded cards.

refundRequest(sequenceNumber, account)

Reclaims the fee for a request unrevealed past the refund delay.

getRequest(sequenceNumber) / getProvider(address)

Read the raw on-chain Request / Provider structs.

Deck decoding

Card id <-> rank/suit

decodeCard(id) / decodeCards(ids)

Turns a 0-51 card id (or array of them) into { rank, suit, suitSymbol, label }.

RANKS / SUITS / SUIT_SYMBOLS

The raw lookup tables decodeCard is built on, in case you need custom rendering.

Hash chain helpers

Shared by the contracts package's deploy script and the Dealer keeper - see the whitepaper for the underlying scheme.

Dealer commit-reveal chains

generateHashChain(length, seed?)

Builds a dealer's hash chain. Used by the deploy script and the Dealer keeper.

chainTip(chain) / maxReveals(chain)

The value to publish via registerProvider, and how many reveals the chain supports.

revealForRequestIndex(chain, index)

The reveal value for the Nth (0-indexed) request served by this chain.

verifyReveal(revealedValue, previousCommitment)

Independently checks a reveal the same way CardEntropy does on-chain.

Full source: packages/sdk