Skip to content

README.md

Latest commit

 

History

History
418 lines (314 loc) · 12 KB

README.md

File metadata and controls

418 lines (314 loc) · 12 KB

BingoCube White Paper Collection

Version: 1.1
Date: December 26, 2025
Status: Reference Implementation Ready

Overview

This directory contains the comprehensive technical documentation for BingoCube, a novel multi-dimensional visual verification system designed for the ecoPrimals ecosystem.

BingoCube bridges human-recognizable visual patterns with cryptographic security, enabling progressive trust revelation, identity verification, content fingerprinting, and computation proofs—all rendered through petalTongue's multi-modal capabilities.

Documents

1. BingoCube-Overview.md 📘

Primary introduction and conceptual foundation

Contents:

  • Abstract and motivation
  • Core concept (two-board cross-binding)
  • Progressive reveal mathematics
  • Use cases across all primals
  • Simple worked examples
  • Security properties overview
  • Implementation considerations
  • Future directions

Audience: All readers (start here!)
Length: ~45 pages
Key Takeaway: Understand what BingoCube is and why it matters

2. BingoCube-Mathematical-Foundation.md 🔬

Rigorous mathematical analysis and security proofs

Contents:

  • Formal definitions and notation
  • Combinatorial properties (board counting, collision probability)
  • Hash-based cross-binding theorems
  • Progressive reveal mathematics
  • Security proofs (pre-image resistance, binding, collision resistance)
  • Information theory (entropy, conditional entropy)
  • Attack analysis (brute force, meet-in-middle, quantum)

Audience: Cryptographers, security auditors, researchers
Length: ~30 pages
Key Takeaway: Rigorous proof that BingoCube is secure

3. BingoCube-Ecosystem-Examples.md 🌐

Practical integration patterns and use cases

Contents:

  • BearDog: Identity verification with progressive reveal protocol
  • Songbird: P2P trust stamps and federation trust
  • NestGate: Content fingerprints and visual git commits
  • ToadStool: Computation proofs and progress visualization
  • petalTongue: Multi-modal rendering (visual, audio, animation)
  • Cross-primal workflows (identity-verified storage, trusted compute, federated identity, content provenance)

Audience: Primal developers, integration engineers, product designers
Length: ~35 pages
Key Takeaway: How to use BingoCube in your primal

4. BingoCube-Biometric-Identity.md 🆔 ⭐ NEW!

Biometric-seeded identity and zero-knowledge access

Contents:

  • Biometric-seeded identity architecture (ephemeral biometric, permanent cube)
  • Progressive trust verification protocols (20% → 50% → 100%)
  • Homeless services use case (detailed registration, cross-org, mobility)
  • Medical data sovereignty (professional courtesy pattern, dual-key encryption)
  • Sovereign data vaults (user-owned, portable, auditable)
  • Primal integration patterns (BearDog, NestGate, Songbird, ToadStool)
  • Security analysis (threat model, attack scenarios, formal claims)
  • Privacy guarantees (GDPR/CCPA compliance, unlinkability)
  • Comparison to existing systems (biometrics, blockchain, OAuth, PGP)
  • Future directions (multi-factor, hierarchical, threshold recovery)

Audience: Identity system designers, social services organizations, medical privacy advocates, policy makers
Length: ~70 pages
Key Takeaway: How to build sovereign identity systems without biometric honeypots

Quick Start

For Executives / Decision Makers

Read: BingoCube-Overview.md (Sections 1-4, 9)
Time: 15 minutes
Goal: Understand the vision and ecosystem impact

For Developers

Read:

  1. BingoCube-Overview.md (all)
  2. BingoCube-Ecosystem-Examples.md (your primal's section)

Time: 1 hour
Goal: Implement BingoCube in your primal

For Identity System Designers

Read:

  1. BingoCube-Overview.md (Sections 1-4)
  2. BingoCube-Biometric-Identity.md (all)

Time: 2 hours
Goal: Understand sovereign identity architecture and implementation patterns

For Security Auditors

Read:

  1. BingoCube-Overview.md (Section 6)
  2. BingoCube-Mathematical-Foundation.md (all)

Time: 2 hours
Goal: Verify security claims

For Researchers

Read: All documents
Time: 4 hours
Goal: Deep understanding and potential extensions

Key Concepts at a Glance

Two-Board Cross-Binding

Board A (L×L grid)  +  Board B (L×L grid)
         ↓                      ↓
    Hash each cell(i,j) using both A[i,j] and B[i,j]
                     ↓
            Color Grid (L×L)

Progressive Reveal Parameter

x ∈ (0,1] controls how many cells are visible

x=0.2 → 20% of cells (initial trust)
x=0.5 → 50% of cells (moderate trust)
x=1.0 → 100% of cells (full reveal)

Nested Mask Property

𝓜₀.₂ ⊂ 𝓜₀.₅ ⊂ 𝓜₁.₀

Lower x reveals are always subsets of higher x reveals
→ Enables trust building over time

Security Summary

Forgery Probability: ~K^(-x·L²)

Example (L=5, K=16, x=0.5):
  P(forge) ≈ 16^(-12.5) ≈ 2^(-50)
  
→ Even partial reveals are cryptographically secure

Visual Example (L=3)

Full BingoCube at x=1.0

┌─────────┐
│ 🟥 🟩 🟥│
│ 🟥 🟦 🟥│
│ 🟦 🟦 🟦│
└─────────┘

Progressive Reveal Sequence

x=0.33 (33%)      x=0.67 (67%)      x=1.00 (100%)
┌─────────┐      ┌─────────┐      ┌─────────┐
│ ·  🟩 · │      │ 🟥 🟩 · │      │ 🟥 🟩 🟥│
│ ·  ·  🟥│      │ ·  🟦 🟥│      │ 🟥 🟦 🟥│
│ ·  🟦 · │      │ ·  🟦 🟦│      │ 🟦 🟦 🟦│
└─────────┘      └─────────┘      └─────────┘

Use Cases Summary

Primal Use Case Visual Benefit
BearDog Identity verification Progressive trust building
Songbird P2P trust stamps Visual peer recognition
NestGate Content fingerprints Visual commit/file hashes
ToadStool Computation proofs Real-time progress visualization
petalTongue Multi-modal rendering Universal representation system

Real-World Applications

Domain Application Key Innovation
Homeless Services Instant registration, cross-org data sharing No ID required, portable vault
Medical Privacy Sovereign data, professional courtesy Dual-key encryption, patient owns data
Refugee Support Identity without documents Biometric-seeded, regenerable
Disaster Response Rapid identity establishment 2-second registration, offline-capable

Security Properties

✅ Pre-image resistance: Cannot recover boards from color grid
✅ Collision resistance: Different boards → different grids
✅ Binding: Color grid commits to both boards
✅ Partial reveal security: Revealing subset doesn't leak unrevealed cells
✅ Challenge-response: Cannot forge without knowing boards
✅ Attack resistant: Brute force, meet-in-middle, quantum attacks infeasible

Implementation Status

Component Status Notes
Specification ✅ Complete This whitepaper collection
Core Library 🟡 Planned bingocube-core Rust crate
petalTongue Integration 🟡 Planned Visual, audio, animation renderers
Primal Integrations 🔴 Not Started BearDog, Songbird, NestGate, ToadStool
Test Suite 🔴 Not Started Unit, integration, security tests
Benchmarks 🔴 Not Started Performance analysis

Mathematical Complexity

Board Generation

Time: O(L²)
Space: O(L²)
Randomness: L² secure random values

Hash Computation

Time: O(L²) hash evaluations
Space: O(L²) for scalar field
Hash: BLAKE3 or SHA-256

Subcube Generation

Time: O(L² log L²) for sorting by d[i,j]
Space: O(L²) for mask
Output: O(x·L²) cells

Verification

Time: O(x·L²) hash evaluations
Space: O(x·L²) for subcube
Security: K^(-x·L²) forgery probability

Standard Configurations

Small (Classic Bingo)

L = 5  (5×5 grid, 25 cells)
U = 100  (0-99 number range)
K = 16  (16-color palette)
Entropy: ~385 bits
Forgery (x=0.5): ~2^(-50)

Medium

L = 8  (8×8 grid, 64 cells)
U = 512  (0-511 number range)
K = 64  (64-color palette)
Entropy: ~672 bits
Forgery (x=0.5): ~2^(-192)

Large

L = 12  (12×12 grid, 144 cells)
U = 1000  (0-999 number range)
K = 256  (256-color palette)
Entropy: ~1752 bits
Forgery (x=0.5): ~2^(-576)

API Preview

use bingocube::{BingoCube, Board, Config};

// Generate from seed
let cube = BingoCube::from_seed(b"alice_identity", Config::default());

// Get full color grid
let grid = cube.color_grid();

// Get partial reveal
let subcube = cube.subcube(0.5);  // 50% reveal

// Verify subcube
assert!(cube.verify_subcube(&subcube, 0.5));

// Visualize with petalTongue
let visual = VisualRenderer::render(&cube, 0.5);
let audio = AudioRenderer::sonify(&cube, 0.5);
let animation = AnimationRenderer::animate(&cube, 0.0, 1.0, Duration::from_secs(5));

References

Related Work

  • Visual Hashes: GitHub identicons, RoboHash
  • QR Codes: ISO/IEC 18004 standard
  • Cryptographic Commitments: Pedersen commitments, hash-based commitments
  • Progressive Proofs: Interactive proof systems, zero-knowledge proofs

Cryptographic Foundations

  • BLAKE3: Fast cryptographic hash function
  • SHA-256: NIST standard cryptographic hash
  • Random Oracle Model: Theoretical framework for hash analysis
  • Birthday Bound: Collision probability analysis

ecoPrimals Primals

  • BearDog: Security and identity primal
  • Songbird: P2P networking and discovery primal
  • NestGate: Storage and content addressing primal
  • ToadStool: Distributed computing primal
  • petalTongue: Universal visualization primal

Contributing

This whitepaper collection is a living document. Contributions welcome:

Improvements Needed

  1. Proof Review: Verify mathematical proofs (Section 5 of Mathematical-Foundation)
  2. Attack Analysis: Additional attack vectors (Section 7 of Mathematical-Foundation)
  3. Use Cases: More concrete examples (Ecosystem-Examples)
  4. Implementation: Reference implementation in Rust
  5. Benchmarks: Performance analysis
  6. Formal Verification: Coq/Lean proofs

How to Contribute

  1. Read the relevant document(s)
  2. Identify improvements or questions
  3. Submit issues/PRs to ecoPrimals repository
  4. Tag with bingocube label

License

Copyright: ecoPrimals Team, 2025
License: AGPL-3.0-or-later

Contact

Project: BingoCube (ecoPrimals ecosystem)
petalTongue: Universal visualization primal — see the ecoPrimals organization for repository links.
Whitepaper location: whitePaper/ in this repository.

For questions about BingoCube:

  1. Read this whitepaper collection.
  2. See Implementation Status (above in this document) for roadmap and component status.
  3. Open an issue or discussion on the BingoCube repository.
  4. Contact the ecoPrimals maintainers as appropriate.

Acknowledgments

BingoCube builds on:

  • Bingo game structure: Classic American bingo with B-I-N-G-O columns
  • QR code inspiration: Dense, structured, verifiable visual encoding
  • petalTongue vision: Universal representation for all humans
  • ecoPrimals philosophy: Primal sovereignty, human dignity, distributed trust

Special thanks to the ecoPrimals community for feedback and vision.

Next Steps

  1. For Readers: Start with BingoCube-Overview.md
  2. For Implementers: Read Overview, then Ecosystem-Examples for your primal
  3. For Auditors: Read Mathematical-Foundation
  4. For Everyone: Provide feedback!

End of Index

Last Updated: December 25, 2025
Status: Draft for Review
Version: 1.0