Skip to content
ifiokjrPublic

About

a game where you flip those bits for the solana radar hackathon

Resources

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

119 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bitflip

Bitflip is a one-million-pixel, collaborative Solana canvas. Players claim a 64 × 64 sector, flip up to 16 pixels in one atomic move, permanently seal their artwork, and mint the sealed sector as a Bubblegum V1 compressed NFT.

The product is one responsive Flutter codebase for Android, iOS, macOS, and the web. Serverpod hosts the website, provides the typed mint API, publishes NFT metadata and deterministic SVG art, and keeps the private compression-tree operator behind a wallet-signed authorization boundary.

Architecture

  • bitflip_program — no_std Solana program built on Pina 0.19.0.
  • bitflip_program/clients/dart — generated Pina/Codama Dart client.
  • bitflip_app — responsive Flutter app and website with an embedded mobile spending wallet, Android Mobile Wallet Adapter funding, and browser Wallet Standard signing.
  • bitflip_server — Serverpod 4 backend and generated typed client.
  • bitflip_program/tests/surfpool — real-SBF program integration tests running in isolated Surfpool nodes.
  • bitflip_server/bitflip_server_server/test/surfpool — full Bubblegum cNFT integration against checksum-pinned program artifacts.

The canvas is 1024 × 1024 pixels split into 256 sectors. Each sector coordinate is two u8 values (x, y), avoiding ambiguous packed integers. A raw bitmap uses 512 bytes per sector and is easy to validate, render, and hash.

The canvas is allocated lazily: game initialization creates one protocol-owned public sector, and each later claimant funds the rent for exactly one newly unlocked sector. Owners can list active or sealed sectors at a fixed on-chain SOL price without creating a separate listing account. Bounded campaign governance and finite owner-funded rewards are designed, but not yet implemented. See the sector lifecycle and cost model and proposed section economy.

Development

All commands run inside the reproducible devenv shell. install:all installs the exact Serverpod CLI into the gitignored workspace tool cache and runs it with the Dart SDK bundled by the pinned Flutter release, avoiding host SDK drift:

devenv shell
fvm install 3.47.2
install:all

Start the complete development stack—embedded PostgreSQL, migrations, Serverpod hot reload, API on 8080, and the auto-launched Flutter web app—through devenv:

server:start

To target a mobile device instead, disable Serverpod's web auto-launch and run Flutter in another devenv shell:

server:start --no-flutter
flutter:app run

Build the Flutter WASM website directly into Serverpod's web root. Release commands require explicit configuration; see release readiness for the complete contract.

The audit remediation ledger distinguishes repository controls from deployment, store, and mainnet evidence that still has to be produced outside CI.

build:web
server:start

The Flutter app defaults to devnet signing/RPC and local Serverpod. The Serverpod development environment defaults to local Surfpool. Keep the wallet chain and RPC cluster aligned when running on a device or building a deployment:

flutter:app run \
  --dart-define=SOLANA_WALLET_CHAIN=solana:devnet \
  --dart-define=SOLANA_RPC_URL=https://api.devnet.solana.com \
  --dart-define=SERVERPOD_URL=https://api-staging.bitflip.xyz/

The web build bundles the official Wallet Standard registry and Solana extensions locally. It only offers wallets that support the selected chain, versioned transactions, and exact-message signing. Android and iOS generate a device-bound Ed25519 spending wallet, encrypted through Android Keystore or iOS Keychain. Players can copy its address and fund it from any wallet on the configured network; Android also offers an in-app Mobile Wallet Adapter transfer. The embedded key never leaves the device, is not backed up or exportable yet, and should hold only a small playing balance.

Generation and migrations

generate:clients  # Pina account/instruction client
generate:server   # Serverpod protocol and app client
migration:create  # after changing a .spy.yaml database model

Generated Pina and Serverpod source should never be edited by hand.

Verification

audit:security
lint:all
test:rust
test:surfpool
test:surfpool:cnft
test:server
test:wallet
test:operations
test:flutter
test:flutter:integration
build:server
build:web
build:container

test:surfpool builds the actual SBF program with its public test authority in an isolated target directory before testing, so it cannot replace the deployable production artifact. test:surfpool:cnft deploys Bitflip, Bubblegum, Account Compression, and Noop to an offline Surfnet, then proves that minting and recording the Pina receipt are atomic and idempotent. The external binaries are fetched from a pinned commit and SHA-256 verified. Serverpod tests use its managed embedded PostgreSQL and do not require Docker. test:wallet checks chain/feature filtering and rejects wallets that return altered signed-message bytes.

build:container builds committed sources plus the generated Flutter site in an isolated context. It adds inert credential canaries, verifies Docker context exclusions, and scans every production image layer for them. Local ignored credentials are never read. The runtime image includes only public development, staging, and production configuration; supply deployment secrets separately.

Compressed-NFT minting

Configure these as deployment secrets; never commit them:

  • BITFLIP_MERKLE_TREE — a private Bubblegum V1 tree.
  • BITFLIP_OPERATOR_PRIVATE_KEY — JSON bytes for the tree delegate and the on-chain Bitflip collection authority.
  • BITFLIP_METADATA_BASE_URL — the public Serverpod web origin.
  • SOLANA_RPC_URL — the cluster RPC endpoint.
  • BITFLIP_COLOUR_INDEXER_ENABLED=true — required outside local development.
  • BITFLIP_COLOUR_INDEXER_START_SIGNATURE — the confirmed ABI-v7 launch transaction used as the durable history anchor.
  • SERVERPOD_DATABASE_PASSWORD — the managed PostgreSQL password.
  • SERVERPOD_SERVICE_SECRET — a unique, high-entropy Serverpod service secret.

The owner requests a five-minute challenge, signs its exact text with their wallet, and submits the signature to Serverpod. The backend re-reads the Pina accounts, verifies ownership and sealed state, rate-limits and consumes the challenge, then sends Bubblegum mint and Bitflip receipt instructions in one transaction. A private tree prevents outside mints from racing the predicted leaf index. The beta must run one mint-capable server process because its operator gate is process-local; durable single-consumer work is a mainnet gate.

The contested colour canvas is reconstructed from confirmed Bitflip program transactions. Client submissions are only low-latency hints: a recurring Serverpod worker scans from a persisted cursor, holds a crash-expiring database lease, and safely replays events using per-pixel section revisions.

Security properties

  • No reward faucet or no-op payout exists.
  • Duplicate pixel coordinates are rejected on-chain.
  • Claim and flip prices include explicit client slippage ceilings.
  • Game initialization creates exactly one protocol-owned public sector.
  • Later claims unlock deterministically and in sequence, with the claimant paying account rent.
  • Fixed-price sector resale transfers payment and ownership atomically; minted sectors cannot split ownership from their cNFT.
  • Only the configured authority can start the next game and its unlock clock.
  • Only a sector owner can seal; sealing is irreversible.
  • Only the attested collection authority can record a mint.
  • Authority changes use a two-step propose/accept flow.
  • Mint authorizations bind wallet, game, sector, nonce, expiry, and action and are single-use.
  • Compressed mint and on-chain asset receipt succeed or fail atomically.

See security.md for reporting and operational requirements.

License

See LICENSE.

About

a game where you flip those bits for the solana radar hackathon

Resources

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages