TokenMosaic

Website · Mirror Site · Code

TokenMosaic is a research prototype for shared token economics: a protocol that turns idle tokens, local compute, model calls, tool execution, and human effort into verifiable work for large public-good tasks.

The code in this repository is based on the anonymous TokenShare prototype and has been renamed and packaged as tokenmosaic. The paper PDF is intentionally not included in this repository.

Authors: Hongzhan Tu, Zhizhou Wang, Yan Hu, Benyou Wang.

Core Idea

Large AI-assisted tasks are rarely solved by one prompt. They need planning, decomposition, execution, verification, revision, merging, and provenance tracking. TokenMosaic treats those steps as a protocol:

1. A task owner registers a large task and a token/resource budget.
2. A coordinator decomposes the task into a tree or DAG of atomic units.
3. Heterogeneous clients execute subtasks with local validation.
4. Verifier nodes or task-specific checkers accept, reject, or requeue outputs.
5. Accepted outputs are recursively merged.
6. A ledger records assignments, artifacts, verification events, provenance, rewards, and penalties.

Unlike proof-of-work systems that spend compute on artificial puzzles, TokenMosaic aims to coordinate useful computation: scientific workflows, formal proof work, benchmark construction, data annotation, and other tasks where producing an answer is expensive but checking intermediate evidence is possible.

What This Prototype Provides

• A local protocol engine for task registration, scheduling, leases, attempts, verification, merge, replay, and settlement.
• Append-only JSONL event logs plus SQLite projections for auditability.
• Artifact storage with content hashes.
• Plugin boundaries for task-specific decomposition, execution, verification, and merge logic.
• Proof-of-concept plugins for integer factorization and Lean proof workflows.
• Experimental executors, including deterministic/mock execution and an opt-in AI API executor path.
• Reproducible tests for protocol invariants, storage, plugins, execution flow, and experiment runners.

Repository Map

• src/tokenmosaic/: Python package for the protocol core, storage, executors, plugins, replay, and experiments.
• tests/: pytest suite mirroring the package boundaries.
• fixtures/lean_proof_project/: local Lean fixture project used by the Lean proof plugin tests.
• Doc/TechnicalDocument/: design notes and engineering references inherited from the prototype.
• docs/: lightweight project documentation and plans.

Install

TokenMosaic currently requires Python 3.11 or newer.

python -m venv .venv
. .venv/Scripts/activate  # Windows PowerShell users can use .venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .

For a test-only setup without editable install:

set PYTHONPATH=src
python -m pytest tests

On Bash / WSL:

export PYTHONPATH=src
python -m pytest tests

Quick Checks

python -m compileall -q src tests
python -m pytest tests/core tests/storage tests/plugins/factorization

Some Lean-related tests require a working Lean/lake toolchain. AI API smoke tests are opt-in and should not run unless local, gitignored credentials are configured.

Paper Summary

TokenMosaic frames tokens as units of intelligent work. The paper argues that future public-good tasks will exceed the budget of any single user or organization, while many devices, models, cloud credits, and human contributors remain idle. The proposed solution is a protocol layer that pools those distributed capacities without simply trusting them.

The central mechanism is a recursively decomposable task graph. Each leaf unit has an explicit input, output contract, verifier, cost estimate, and merge rule. Invalid work can be rejected or reassigned; valid work becomes part of a provenance-backed final result. Rewards are settled through a contribution ledger, making the final answer not just generated, but auditable.

The paper emphasizes five design desiderata:

• Decomposability: large work should break into task units with clear dependencies.
• Local verifiability: each subtask should have a checker, rubric, quorum, or formal verifier.
• Extendability: task-specific logic lives in plugins rather than in the protocol core.
• Scalability: additional contributors should improve speed, quality, redundancy, or fault tolerance.
• Autonomy: routine assignment, validation, timeout recovery, merging, and settlement should proceed by rules.

Project Site

The project website is maintained separately in the GitHub Pages repository:

• Primary target: https://tokenmosaic.github.io/
• Current mirror: https://freedomintelligence.github.io/TokenMosaic.github.io/

License

This repository preserves the license inherited from the prototype. See LICENSE.

Citation

If you use TokenMosaic or refer to the paper, please cite it as:

Plain text

Hongzhan Tu, Zhizhou Wang, Yan Hu, and Benyou Wang. 2026. Shared Your Tokens! A Community Protocol for Composing Distributed Tokens for "Intelligent" Tasks.

BibTeX

@misc{tu2026tokenmosaic,
  title        = {Shared Your Tokens! A Community Protocol for Composing Distributed Tokens for ``Intelligent'' Tasks},
  author       = {Tu, Hongzhan and Wang, Zhizhou and Hu, Yan and Wang, Benyou},
  year         = {2026},
  note         = {Manuscript},
  url          = {https://tokenmosaic.github.io/}
}