Vision

ORCRUX transforme du compute en progres ML verifiable.

Les blocs rejouent un step d'entrainement deterministe.

• Batches deterministes derives du hash precedent
• Verification rejouable sur chaque node
• Rewards alignees sur le progres utile

Proof-of-Useful-Work

Chaque bloc rejoue un step de logistic regression (PyTorch) avec inputs deterministes.

Le hash precedent definit le seed, donc chaque node peut verifier le meme batch.

• work_proof lie model_before/after, metrics et work_seed au hash
• loss delta < 0 = progres utile
• Reproductibilite stricte avec hash stable

Architecture

Un node PoUW regroupe blockchain, stockage LMDB, P2P, controle mineur et API REST.

Les clients (site, GUI, wallet) parlent a l'API; le node produit les blocs et expose les metrics.

• Core Python dans src/pouw
• FastAPI pour la couche REST
• LMDB chain + ledger local JSON

Node & reseau

Le node synchronise blocs et transactions via un reseau P2P asyncio.

Sync incremental, resumes de pairs et metrics exposes pour le monitoring.

• Ports par defaut: P2P 18444, API 8080/8081
• Configurable via pouw.toml et variables d'environnement
• Prometheus sur /metrics
• Sync lite: headers + proofs avant blocs complets

Wallet & identite

wallet.json stocke comptes, cles chiffrees et staking.

L'UI utilise des tokens courts pour securiser les API owner-only.

• Lock/unlock via passphrase + session unlock
• Multi-comptes avec compte par defaut
• Tokens via /auth/token et /auth/me

Tokenomics

Supply CRUX plafonne a 1 000 000 000 tokens.

Rewards: emission de base + bonus loss_delta + facteur staking.

Les pools fondateur liquide, fondateur vesting, rewards minage, rewards IA, faucet, listings et reserve ecosysteme sont maintenant separes.

• RewardPolicy configurable dans pouw.toml
• Frais sur transferts/workloads/votes
• Payout workloads ajuste aux GPU-hours + caps
• Tresorerie alimentee par les frais
• Vesting fondateur = 5,000,000 CRUX tous les 6 mois pendant 4 ans

Transactions & staking

Les transactions sont enregistrees dans un ledger local et integrees aux blocs.

Le staking bloque le solde pour une duree et booste rewards + vote.

• Mempool pour les transferts pending
• Durees de staking avec bonus
• Frais collectes dans l'adresse tresorerie

Gouvernance

Propositions et votes sont on-chain et repliques entre nodes.

Le poids de vote vient du staking (ou du solde disponible).

• POST /governance/proposals
• POST /governance/proposals/{id}/vote
• Timeline via /governance/events

Workloads & marketplace

Les workloads definissent le job ML: modele, dataset, metrics et owner.

Dashboard owner-only et artefacts proteges.

Les templates incluent estimated_gpu_hours pour estimer l'effort avant scheduling.

Le temps mur estime depend de la capacite GPU effective du pool au moment de l'execution.

• Templates + soumission via CLI/API/site
• Queue snapshot pour la marketplace
• Artefacts servis depuis data/workloads/results
• Etats clairs (pending/approved/processing/completed)
• Reference de runtime via reward_policy.estimated_gpu_hours
• Formule recommande: temps_estime ~= estimated_gpu_hours / capacite_pool_effective
• Prochaine etape: capability announce signee (profil GPU, VRAM, slots dispo, heartbeat)
• Le v2 gros modeles supporte artefacts hors chaine (IPFS/URL), adapters/deltas et regles de placement

Catalogue de modeles (guide debutant)

Les templates ORCRUX sont ranges par usage pour aider un debutant a choisir sans expertise avancee en apprentissage automatique.

Commence par les petits templates. Ils sont plus rapides, coutent moins de CRUX et permettent de valider le flux complet avant de monter en gamme.

• Templates texte: question-reponse et generation (DistilBERT, BERT, RoBERTa, variantes Llama)
• Templates image: classification et representation visuelle (ResNet, CLIP, variantes ViT)
• Templates audio: transcription parole vers texte (Whisper tiny/base/small)
• Templates code: comprehension ou generation de code (CodeT5, variantes CodeLlama)
• Templates video: analyse d actions et sequences (VideoMAE, variantes TimeSformer)
• Niveaux de taille: petit (validation rapide), moyen (equilibre), gros/sharde (impact plus fort + cout plus eleve)
• Le champ GPU requirement indique la classe materielle necessaire: auto, gpu_8g, gpu_12g, gpu_24g
• Si tu debutes: publie dataset -> choisis un petit template -> lance un workload -> verifie artefact et rewards

Format dataset (quoi mettre dedans)

ORCRUX genere automatiquement dataset.json depuis le formulaire. Ton travail principal est de preparer un fichier de donnees propre et coherent.

Garde un format simple au debut. Le plus efficace est de commencer petit puis d'augmenter la taille quand le flux est valide.

• Texte: prefere JSONL, une ligne = un exemple, ex {"input":"question","output":"reponse"}
• Image: prefere ZIP avec dossiers par classe, ou labels.csv avec colonnes file,label
• Audio: fichiers WAV/FLAC + transcriptions.csv avec colonnes file,text
• Code: JSONL avec paires instruction/code, ex {"instruction":"...","code":"..."}
• Regles communes: UTF-8, noms de champs stables, pas de doublons evidents, contenu legalement partageable
• Option recommandee: ajouter un split validation pour mesurer le progres de maniere stable

Temps workloads & disponibilite GPU

Les templates ORCRUX exposent estimated_gpu_hours comme base d'effort par type de workload.

Le temps mur attendu depend de la capacite GPU disponible en temps reel sur les mineurs participants.

Le sharding est disponible pour les gros comme les petits workloads (y compris les modeles classe 8 Go).

• Champ de reference: reward_policy.estimated_gpu_hours dans templates.json
• Estimation pratique: temps_estime ~= estimated_gpu_hours / capacite_pool_effective
• Exemples: LogReg 1.5h, CNN-lite 4.5h, Llama 3 8B 16-18h, SDXL 16h
• Endpoint registre GPU: GET /network/gpus (resume + noeuds actifs + TTL)
• Endpoint heartbeat node: POST /network/gpus/heartbeat
• Politique sharding dans workload_v2.sharding: shard_count, min_gpu_vram_gb, strategy
• fit_strategy: auto | prefer_single_big_gpu | prefer_sharded_parallel
• Un workload 8 Go peut tourner sur un GPU 20/24 Go (mode single-big) ou sur plusieurs GPU 8 Go (mode parallel)
• La politique de placement peut imposer une VRAM totale, un debit minimal et un routage meme-machine si necessaire

Deploiement sharding (testnet)

L'execution shardee utilise une progression synchronisee (metrics.shard_progress) et avance la progression globale quand tous les shards progressent.

Cela permet d'accelerer en pratique sur mineurs multi-GPU et futures campagnes multi-noeuds.

• Regler le parallelisme node: POUW_SHARD_PARALLELISM=<n>
• Definir workload_v2.sharding avec shard_count et min_gpu_vram_gb
• Choisir fit_strategy selon l'objectif (single big GPU vs shards paralleles)
• Suivre l'offre GPU en direct dans l'Explorer et /network/gpus
• Verifier la progression shard via les metrics workload (blocks_processed + shard_progress)
• Phase actuelle: cooperative sharding; backends distribues (NCCL/FSDP/DeepSpeed) en phase suivante
• Pour les gros modeles, privilegier adapter_only ou delta_only pour eviter de deplacer un checkpoint complet a chaque round

BYO workloads (sandbox)

Les workloads custom tournent dans une sandbox controlee.

Limites CPU/RAM/GPU, timeouts et reseau coupe.

• Packaging dataset (zip + metadata)
• Verification deterministe + spot checks
• Quotas de ressources configurables + IO limits

API & CLI

FastAPI expose node, wallet, workloads, gouvernance et metrics.

La CLI Typer reflète l'API pour l'automatisation.

• python -m pouw.cli run --mine
• python -m pouw.cli workloads submit/sign/approve
• python -m pouw.cli wallet stake/transfer

SDKs & dApps

SDKs disponibles en Python et JavaScript.

L'extension wallet injecte window.orcrux pour les dApps.

• sdk/python: orcrux_sdk client
• sdk/js: @orcrux/sdk ESM package
• API extension: connect/signMessage/signTransaction

GUI & desktop

GUI Vite pour miner (statut, wallet, workloads) + wrapper Tauri.

Build desktop en binaire natif (Windows/macOS/Linux).

• apps/gui pour le dashboard
• Tauri CLI pour packager
• API configurable via VITE_POUW_API

Desktop Linux

ORCRUX Desktop Linux est distribue en AppImage, deb et rpm.

L'app Linux peut lancer node + mineur en un clic et se connecter a une API VPS distante.

• Canal officiel: GitHub Releases (checksums signes)
• Endpoint API modifiable depuis les parametres desktop
• Scripts principaux: scripts/tauri-linux.sh et scripts/tauri-appimage-manage.sh

Desktop Windows

ORCRUX Desktop Windows est pense pour piloter un node local, synchroniser le wallet et miner depuis un PC gaming.

La stack desktop est faite pour utiliser le backend GPU adapte a la machine: CUDA, ROCm ou DirectML selon la carte et l environnement.

• API locale recommandee: http://127.0.0.1:8080
• Peer bootstrap par defaut: 51.254.141.243:18444
• Seed API recommande: http://51.254.141.243:8080
• Checks GUI essentiels: hauteur locale, hauteur chaine, retard, etat sync, balance disponible et verrouillee
• Backends GPU selon la plateforme: CUDA, ROCm ou DirectML

Testnet & starter pack

Un starter-pack lance: node + API + site Next.js + faucet + daemon IPFS.

Le site proxifie /api/pouw/* vers l'API node via un cookie d'auth.

• API node: http://<ip-vps>:8081
• Site: http://<ip-vps>:3000

Swap testnet (USDC <-> CRUX)

La route publique actuelle est USDC sur Solana Devnet vers CRUX sur ORCRUX, et le chemin inverse de CRUX sur ORCRUX vers USDC sur Solana Devnet.

Phantom est utilise pour la partie Solana, tandis que le wallet ORCRUX du site recoit ou envoie les CRUX cote ORCRUX.

• Faucets utilises pendant les tests: https://faucet.solana.com/ et https://faucet.circle.com/
• Etape 1: installer Phantom et le passer sur Solana Devnet
• Dans Phantom: cliquer sur les trois petits points au-dessus de la liste de tokens, ouvrir Parametres du portefeuille, descendre jusqu'aux parametres pour developpeurs, puis cocher Solana Devnet
• Etape 2: demander du SOL via le faucet Solana Devnet
• Etape 3: demander du USDC testnet via le faucet Circle sur Solana Devnet
• Etape 4: ouvrir https://orcrux.xyz/dashboard, connecter le wallet ORCRUX puis connecter Phantom
• Etape 5: tester USDC -> CRUX avec un petit montant et confirmer dans Phantom
• Etape 6: tester CRUX -> USDC avec un petit montant et verifier le payout USDC dans Phantom
• Le dashboard expose les etats: awaiting_deposit, confirming, processing, completed, failed

Securite & monitoring

Permissions API enforcees par token de session.

Prometheus/Grafana disponibles dans monitoring/.

• Auth TTL via POUW_AUTH_TTL_SECONDS
• Acces owner-only aux workloads
• Alertes peer drop et loss regression
• Rotation logs + pruning artefacts optionnel