PlayFrens — On-Chain Multiplayer Gaming Without Gas Fees

PlayFrens is an on-chain multiplayer game platform that solves one of the biggest UX problems in blockchain gaming — gas fees and latency on every action.

Built on Yellow Network state channels (ERC-7824), PlayFrens lets friends find each other by ENS name, deposit tokens once, and play unlimited poker hands with zero gas fees and instant settlement.

---

Judge Clarification

An earlier experimental project was developed within the GetFrens monorepo (https://github.com/getfrens/monorepo), but it was based on a different and more complex concept — a MetaMask-like wallet extension designed to interact with memecoins directly from Twitter posts. Due to technical complexity, unresolved blockers, and reduced team interest, that effort was discontinued.

PlayFrens is a completely new project built independently from scratch by me (Deven Rathod) as a solo developer for this hackathon submission. All gameplay, state channel integration, and architecture described here were implemented specifically for this project. No production code from the earlier repository is reused in this submission.

Core Insight

A 4-player poker game with 100 hands should produce zero on-chain transactions during gameplay.

Only the initial deposit and final withdrawal touch the blockchain.

Everything in between — dealing cards, placing bets, showdowns, and pot distribution — happens off-chain through cryptographically signed state updates on Yellow Network’s Clearnode, giving players:

• The speed of a centralized server
• The security of on-chain funds

---

How a Typical Session Works

1. Players connect their wallet and authorize with Yellow Network.
2. They create or join a poker table.
3. The host sets the buy-in, blinds, and chip denominations.
4. When the first hand is dealt, all players co-sign a multi-party app session that locks their buy-in from their Unified Balance on Clearnode.
5. Gameplay happens in real-time via Socket.io:
   • Check
   • Bet
   • Fold
   • Raise
6. The server computes updated chip allocations and submits signed state updates to Clearnode after each hand.

Result:
No gas. No block confirmations. Just instant poker.

When the session ends:

• Funds return to each player’s Unified Balance proportional to their chip count.
• Players can withdraw back to their wallet at any time.

---

Social Layer (ENS Integration)

PlayFrens integrates ENS to make multiplayer discovery seamless:

• Search for friends by their .eth name
• Display ENS avatars at the poker table
• Invite friends directly to rooms

---

Game-Agnostic Architecture

While poker is the first game, the platform is designed to support any turn-based game that tracks chip or score balances.

The following components are reusable across games:

• Fund flow
• Session management
• Settlement layer

---

Smart Contract Usage

PlayFrens does not deploy custom smart contracts.

Instead, it uses Yellow Network’s existing infrastructure:

• Custody Contract — fund security
• Adjudicator Contract — dispute resolution
• ytest.usd — game token

All deployments currently run on Base Sepolia.

PlayFrens Technical Architecture

PlayFrens is built as a pnpm monorepo powered by Turborepo, split into three main packages:

• Frontend — React 19 + Vite
• Game Server — Node.js
• Shared Package — Types and constants compiled with tsup

---

Poker Engine & Real-Time Layer

The server wraps the poker-ts library inside a PokerRoom class that extends an abstract GameRoom base.

All game logic runs server-side:

• The poker-ts engine handles:
  • Card dealing
  • Betting rounds
  • Showdowns
  • Pot calculation

Game state is broadcast individually via Socket.io so that:

• Each player only sees their own hole cards
• Opponents’ cards remain hidden until showdown

Fault Tolerance

The server supports deferred player removal:

• If a player disconnects mid-hand:
  • They are automatically folded when their turn arrives
  • They are cleanly removed once the hand completes

---

Yellow Network Integration

This is the core infrastructure layer.

The server runs a YellowClient that maintains a persistent WebSocket connection to Clearnode and authenticates using EIP-712 signed challenges.

The server wallet acts as a Trusted Judge with:

• weight = 100
• quorum = 100

This makes the server the sole authority on state updates during gameplay, while still requiring all players to co-sign the initial session creation.

---

Multi-Party Signing Flow

The initial session creation involves a coordinated multi-signature process:

1. When the host clicks Deal Cards for the first time:

   • The server prepares an app session request using createAppSessionMessage from @erc7824/nitrolite.

2. The server signs the request with its own session key using raw ECDSA (createECDSAMessageSigner, not EIP-191 prefixed).

3. The unsigned payload is broadcast to each player's browser via Socket.io.

4. Each browser:

   • Uses its own YellowRpcClient
   • Authenticates independently with Clearnode using an ephemeral session key
   • Signs the payload locally

5. The server’s YellowSessionManager:

   • Collects all player signatures
   • Bundles them into a single multi-sig message containing the request and all signatures

6. The bundled request is submitted to Clearnode.

7. Clearnode:

   • Recovers each signer
   • Maps session keys to wallet addresses
   • Verifies all required signatures
   • Creates the app session

After the initial co-sign:

• Subsequent hands start instantly
• The server submits state updates unilaterally as the Trusted Judge

---

Important Implementation Detail

All addresses sent to Clearnode must be EIP-55 checksummed, as Clearnode performs case-sensitive comparisons.

PlayFrens normalizes addresses using getAddress() from viem before any RPC call.

---

State Updates & Settlement

After every hand:

• The server calls submitAppState with updated chip-to-token allocations:

playerChips × chipUnit = ytest.usd amount

When a player cashes out:

• closeAppSession sends final allocations
• Funds return to each player's Unified Balance

---

ENS Integration

wagmi is configured with:

• Base Sepolia (gameplay)
• Ethereum Mainnet (ENS resolution)

The frontend uses:

• useEnsName
• useEnsAvatar
• useEnsAddress

These enable:

• Friend search by ENS
• Player identity display

The RainbowKit chain selector is hidden using chainStatus="none" so users are not confused by the dual-chain setup, while mainnet remains enabled for ENS lookups.

---

Frontend Stack

• React 19
• Tailwind CSS v4
  • Uses @import "tailwindcss" and @theme block syntax
  • No tailwind.config.js
• Motion (Framer Motion v11+) for animations
• RainbowKit v2 + wagmi v2 for wallet connectivity

The app uses state-driven routing:

• Lobby
• Room
• Game

Views are rendered based on game state rather than URL routing.

---

Deposit & Withdrawal Flow

Players can obtain testnet tokens via:

• Clearnode faucet endpoint
• Or a real on-chain deposit using ERC20 approve + Custody.deposit()

Contracts and ABIs:

• CustodyAbi
• Erc20Abi
• Exported from @erc7824/nitrolite

Withdrawals use:

• Custody.withdraw() to return tokens to the wallet.

Frontend hooks:

• useCustody
• useYellow

These manage deposit, withdrawal, and balance operations.

---

Deployment

The game server is containerized using a multi-stage Dockerfile:

• Builds shared and server packages with tsup
• Produces a slim production image

Deployment:

• Hosted on Fly.io
• WebSocket support enabled
• Auto-scaling configured