Sprint 5 : integration et production -- securite, performance, API publique, documentation
Backend: rate limiter, security headers, blockchain cache service avec RPC, public API (7 endpoints read-only), WebSocket auth + heartbeat, DB connection pooling, structured logging, health check DB. Frontend: API retry/timeout, WebSocket auth + heartbeat + typed events, notifications toast, mobile hamburger + drawer, error boundary, offline banner, loading skeletons, dashboard enrichi. Documentation: guides utilisateur complets (demarrage, vote, sanctuaire, FAQ 30+), guide deploiement, politique securite. 123 tests, 155 fichiers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
@@ -5,13 +5,61 @@ description: Architecture, API et reference technique de Glibredecision
|
||||
|
||||
# Documentation technique
|
||||
|
||||
Bienvenue dans la documentation technique de Glibredecision.
|
||||
Bienvenue dans la documentation technique de Glibredecision, la plateforme de decisions collectives pour la communaute Duniter/G1.
|
||||
|
||||
## Presentation
|
||||
|
||||
Glibredecision est une plateforme de gouvernance decentralisee qui permet aux membres de la Toile de Confiance (WoT) Duniter V2 de gerer des documents de reference modulaires sous vote permanent, prendre des decisions collectives multi-etapes, attribuer des mandats et archiver de maniere immuable les resultats via IPFS et la blockchain Duniter.
|
||||
|
||||
## Stack technique
|
||||
|
||||
| Couche | Technologie |
|
||||
| ------------ | -------------------------------------------------- |
|
||||
| Frontend | Nuxt 4 + Nuxt UI v3 + Pinia + UnoCSS |
|
||||
| Backend | Python FastAPI + SQLAlchemy 2.0 (async) + Pydantic v2 |
|
||||
| Base de donnees | PostgreSQL 16 (asyncpg) |
|
||||
| Authentification | Duniter V2 Ed25519 challenge-response |
|
||||
| Sanctuaire | IPFS (kubo) + hash on-chain (system.remark) |
|
||||
| CI/CD | Woodpecker CI + Docker + Traefik |
|
||||
| Temps reel | WebSocket pour les mises a jour de vote en direct |
|
||||
|
||||
## Historique des sprints
|
||||
|
||||
| Sprint | Contenu principal | Statut |
|
||||
| ------ | ----------------- | ------ |
|
||||
| Sprint 1 | Architecture, modeles de base (documents, items, versions, identites, protocoles, formules), API documents et authentification | Termine |
|
||||
| Sprint 2 | Sanctuaire (IPFS + on-chain), gestion complete des items (CRUD, reorder), verification d'integrite, archivage de documents | Termine |
|
||||
| Sprint 3 | Systeme de vote complet (sessions, votes signes, seuil WoT, criteres Smith/TechComm), meta-gouvernance, simulateur de formules, WebSocket temps reel | Termine |
|
||||
| Sprint 4 | Decisions multi-etapes (workflow, avancement, vote lie), mandats (candidature, election, assignation, revocation), vote nuance | Termine |
|
||||
| Sprint 5 | Stabilisation, documentation complete, deploiement production, audit securite | En cours |
|
||||
|
||||
## Version et statut
|
||||
|
||||
- **Version** : 1.0.0-rc
|
||||
- **Statut** : Release candidate -- Sprint 5 (documentation et stabilisation)
|
||||
- **Depot** : [git.duniter.org/tools/glibredecision](https://git.duniter.org/tools/glibredecision)
|
||||
|
||||
## Sections
|
||||
|
||||
- [Architecture](/dev/architecture) -- Vue d'ensemble de l'architecture
|
||||
- [Reference API](/dev/api-reference) -- Endpoints et schemas
|
||||
- [Schema de base de donnees](/dev/database-schema) -- Tables et relations
|
||||
- [Formules](/dev/formulas) -- Formules mathematiques de seuil
|
||||
- [Integration blockchain](/dev/blockchain-integration) -- Duniter V2, IPFS, on-chain
|
||||
- [Contribution](/dev/contributing) -- Guide de contribution
|
||||
### Architecture et conception
|
||||
|
||||
- [Architecture](/dev/architecture) -- Vue d'ensemble de l'architecture, stack, flux de communication
|
||||
|
||||
### Reference technique
|
||||
|
||||
- [Reference API](/dev/api-reference) -- Tous les endpoints REST et WebSocket avec schemas
|
||||
- [Schema de base de donnees](/dev/database-schema) -- Tables, colonnes, relations et diagramme
|
||||
|
||||
### Domaines fonctionnels
|
||||
|
||||
- [Formules](/dev/formulas) -- Formules mathematiques de seuil WoT, criteres Smith/TechComm, simulateur, meta-gouvernance
|
||||
- [Integration blockchain](/dev/blockchain-integration) -- Duniter V2 RPC, IPFS, ancrage on-chain
|
||||
|
||||
### Operations
|
||||
|
||||
- [Deploiement](/dev/deployment) -- Docker, Traefik, migrations, sauvegarde, mise a jour, troubleshooting
|
||||
- [Securite](/dev/security) -- Authentification, integrite des votes, rate limiting, en-tetes, audit
|
||||
|
||||
### Contribution
|
||||
|
||||
- [Guide de contribution](/dev/contributing) -- Installation locale, conventions, tests, processus de contribution
|
||||
|
||||
405
docs/content/dev/8.deployment.md
Normal file
405
docs/content/dev/8.deployment.md
Normal file
@@ -0,0 +1,405 @@
|
||||
---
|
||||
title: Deploiement
|
||||
description: Guide de deploiement en production de Glibredecision
|
||||
---
|
||||
|
||||
# Deploiement
|
||||
|
||||
Ce guide couvre le deploiement complet de Glibredecision en production avec Docker, Traefik, PostgreSQL et IPFS.
|
||||
|
||||
## Prerequis
|
||||
|
||||
| Composant | Version minimale | Description |
|
||||
| --------- | ---------------- | ----------- |
|
||||
| Docker | 24+ | Moteur de conteneurs |
|
||||
| Docker Compose | 2.20+ | Orchestration multi-conteneurs |
|
||||
| Nom de domaine | -- | Domaine pointe vers le serveur (ex: `glibredecision.org`) |
|
||||
| Certificat TLS | -- | Genere automatiquement par Traefik via Let's Encrypt |
|
||||
| Traefik | 2.10+ | Reverse proxy avec terminaison TLS (reseau externe `traefik`) |
|
||||
| Serveur | 2 vCPU, 4 Go RAM, 40 Go SSD | Ressources recommandees |
|
||||
|
||||
### Reseau Traefik
|
||||
|
||||
Le deploiement suppose qu'un reseau Docker externe `traefik` existe deja avec une instance Traefik configuree. Si ce n'est pas le cas, creez-le :
|
||||
|
||||
```bash
|
||||
docker network create traefik
|
||||
```
|
||||
|
||||
Et deployez Traefik separement (voir section [Configuration Traefik](#configuration-traefik)).
|
||||
|
||||
## Configuration .env
|
||||
|
||||
Copiez le fichier `.env.example` et configurez chaque variable pour la production :
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### Variables d'environnement
|
||||
|
||||
| Variable | Description | Valeur par defaut | Production |
|
||||
| -------- | ----------- | ----------------- | ---------- |
|
||||
| `POSTGRES_DB` | Nom de la base de donnees | `glibredecision` | `glibredecision` |
|
||||
| `POSTGRES_USER` | Utilisateur PostgreSQL | `glibredecision` | `glibredecision` |
|
||||
| `POSTGRES_PASSWORD` | Mot de passe PostgreSQL | `change-me-in-production` | **Generer un mot de passe fort** (32+ caracteres) |
|
||||
| `DATABASE_URL` | URL de connexion asyncpg | `postgresql+asyncpg://...@localhost:5432/...` | Construite automatiquement dans docker-compose |
|
||||
| `SECRET_KEY` | Cle secrete pour les tokens de session | `change-me-in-production-with-a-real-secret-key` | **Generer une cle aleatoire** (`openssl rand -hex 64`) |
|
||||
| `DEBUG` | Mode debug | `true` | **`false`** |
|
||||
| `CORS_ORIGINS` | Origines CORS autorisees | `["http://localhost:3002"]` | `["https://glibredecision.org"]` |
|
||||
| `DUNITER_RPC_URL` | URL du noeud Duniter V2 RPC | `wss://gdev.p2p.legal/ws` | URL du noeud de production |
|
||||
| `IPFS_API_URL` | URL de l'API IPFS (kubo) | `http://localhost:5001` | `http://ipfs:5001` (interne Docker) |
|
||||
| `IPFS_GATEWAY_URL` | URL de la passerelle IPFS | `http://localhost:8080` | `http://ipfs:8080` (interne Docker) |
|
||||
| `NUXT_PUBLIC_API_BASE` | URL publique de l'API pour le frontend | `http://localhost:8002/api/v1` | `https://glibredecision.org/api/v1` |
|
||||
| `DOMAIN` | Nom de domaine | `glibredecision.org` | Votre domaine |
|
||||
|
||||
### Generer les secrets
|
||||
|
||||
```bash
|
||||
# Generer POSTGRES_PASSWORD
|
||||
openssl rand -hex 32
|
||||
|
||||
# Generer SECRET_KEY
|
||||
openssl rand -hex 64
|
||||
```
|
||||
|
||||
::callout{type="warning"}
|
||||
Ne commitez jamais le fichier `.env` contenant les secrets de production. Ajoutez-le au `.gitignore`.
|
||||
::
|
||||
|
||||
## Lancement avec docker-compose
|
||||
|
||||
### Premier deploiement
|
||||
|
||||
```bash
|
||||
# Se placer dans le repertoire du projet
|
||||
cd /opt/glibredecision
|
||||
|
||||
# Cloner le depot
|
||||
git clone https://git.duniter.org/tools/glibredecision.git .
|
||||
|
||||
# Configurer l'environnement
|
||||
cp .env.example .env
|
||||
# Editer .env avec les valeurs de production
|
||||
|
||||
# Construire et demarrer les services
|
||||
docker compose -f docker/docker-compose.yml up -d --build
|
||||
|
||||
# Verifier que tous les services sont sains
|
||||
docker compose -f docker/docker-compose.yml ps
|
||||
```
|
||||
|
||||
### Services deployes
|
||||
|
||||
| Service | Description | Port interne | Expose |
|
||||
| ------- | ----------- | ------------ | ------ |
|
||||
| `postgres` | Base de donnees PostgreSQL 16 | 5432 | Non (interne uniquement) |
|
||||
| `backend` | API FastAPI | 8002 | Via Traefik (`/api/*`) |
|
||||
| `frontend` | Application Nuxt 4 | 3000 | Via Traefik (racine) |
|
||||
| `ipfs` | Noeud IPFS kubo | 5001, 8080 | Non (interne uniquement) |
|
||||
|
||||
### Verifier le deploiement
|
||||
|
||||
```bash
|
||||
# Statut des conteneurs
|
||||
docker compose -f docker/docker-compose.yml ps
|
||||
|
||||
# Logs d'un service specifique
|
||||
docker compose -f docker/docker-compose.yml logs -f backend
|
||||
|
||||
# Health check de l'API
|
||||
curl -s https://glibredecision.org/api/health | jq .
|
||||
```
|
||||
|
||||
## Migration de base de donnees (Alembic)
|
||||
|
||||
Glibredecision utilise Alembic pour les migrations de schema PostgreSQL.
|
||||
|
||||
### Appliquer les migrations
|
||||
|
||||
```bash
|
||||
# Executer les migrations dans le conteneur backend
|
||||
docker compose -f docker/docker-compose.yml exec backend alembic upgrade head
|
||||
```
|
||||
|
||||
### Verifier l'etat des migrations
|
||||
|
||||
```bash
|
||||
docker compose -f docker/docker-compose.yml exec backend alembic current
|
||||
```
|
||||
|
||||
### Creer une nouvelle migration
|
||||
|
||||
```bash
|
||||
# En developpement uniquement
|
||||
docker compose -f docker/docker-compose.yml exec backend alembic revision --autogenerate -m "description de la migration"
|
||||
```
|
||||
|
||||
### Rollback d'une migration
|
||||
|
||||
```bash
|
||||
# Revenir d'une migration
|
||||
docker compose -f docker/docker-compose.yml exec backend alembic downgrade -1
|
||||
```
|
||||
|
||||
## Seed des donnees initiales
|
||||
|
||||
Apres la premiere migration, vous pouvez charger les donnees de seed (documents de reference initiaux) :
|
||||
|
||||
```bash
|
||||
# Executer le script de seed dans le conteneur backend
|
||||
docker compose -f docker/docker-compose.yml exec backend python -m app.seed
|
||||
```
|
||||
|
||||
Les donnees de seed incluent :
|
||||
|
||||
- La Licence G1 avec ses items
|
||||
- L'Engagement Forgeron v2.0.0
|
||||
- L'Engagement Comite Technique v2.0.0
|
||||
- Le template de processus de Runtime Upgrade
|
||||
- Les protocoles de vote par defaut avec leurs formules
|
||||
|
||||
## Configuration Traefik
|
||||
|
||||
### Configuration minimale Traefik
|
||||
|
||||
Si vous n'avez pas encore Traefik, voici une configuration minimale. Creez un fichier `docker-compose.traefik.yml` :
|
||||
|
||||
```yaml
|
||||
version: "3.9"
|
||||
|
||||
services:
|
||||
traefik:
|
||||
image: traefik:v2.10
|
||||
restart: unless-stopped
|
||||
command:
|
||||
- "--api.dashboard=false"
|
||||
- "--providers.docker=true"
|
||||
- "--providers.docker.exposedbydefault=false"
|
||||
- "--providers.docker.network=traefik"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
- "--entrypoints.web.http.redirections.entryPoint.to=websecure"
|
||||
- "--entrypoints.web.http.redirections.entryPoint.scheme=https"
|
||||
- "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
|
||||
- "--certificatesresolvers.letsencrypt.acme.email=admin@glibredecision.org"
|
||||
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- "/var/run/docker.sock:/var/run/docker.sock:ro"
|
||||
- "letsencrypt:/letsencrypt"
|
||||
networks:
|
||||
- traefik
|
||||
|
||||
volumes:
|
||||
letsencrypt:
|
||||
|
||||
networks:
|
||||
traefik:
|
||||
external: true
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.traefik.yml up -d
|
||||
```
|
||||
|
||||
### Routage
|
||||
|
||||
Le `docker-compose.yml` de Glibredecision configure automatiquement les labels Traefik :
|
||||
|
||||
- **Frontend** : `Host(glibredecision.org)` sur le port 3000
|
||||
- **Backend** : `Host(glibredecision.org) && PathPrefix(/api)` sur le port 8002
|
||||
- Les deux utilisent le certificat Let's Encrypt (`certresolver=letsencrypt`)
|
||||
- Redirection HTTP vers HTTPS automatique
|
||||
|
||||
### Certificat TLS
|
||||
|
||||
Le certificat est genere automatiquement par Traefik via Let's Encrypt (challenge TLS-ALPN-01). Assurez-vous que :
|
||||
|
||||
1. Le domaine pointe vers l'adresse IP du serveur (enregistrement DNS A)
|
||||
2. Les ports 80 et 443 sont ouverts dans le firewall
|
||||
3. L'adresse email dans la configuration Traefik est valide
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health checks
|
||||
|
||||
Le service PostgreSQL dispose d'un health check integre (`pg_isready`). Le backend expose un endpoint de sante :
|
||||
|
||||
```bash
|
||||
# Health check de l'API
|
||||
curl -s https://glibredecision.org/api/health
|
||||
# Reponse attendue : {"status": "healthy"}
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
# Suivre les logs de tous les services
|
||||
docker compose -f docker/docker-compose.yml logs -f
|
||||
|
||||
# Logs d'un service specifique
|
||||
docker compose -f docker/docker-compose.yml logs -f backend
|
||||
docker compose -f docker/docker-compose.yml logs -f frontend
|
||||
docker compose -f docker/docker-compose.yml logs -f postgres
|
||||
|
||||
# Derniers 100 lignes
|
||||
docker compose -f docker/docker-compose.yml logs --tail=100 backend
|
||||
```
|
||||
|
||||
### Metriques
|
||||
|
||||
Surveillez les indicateurs suivants :
|
||||
|
||||
| Indicateur | Commande | Seuil d'alerte |
|
||||
| ---------- | -------- | --------------- |
|
||||
| CPU/RAM conteneurs | `docker stats` | > 80% RAM |
|
||||
| Espace disque | `df -h` | > 85% |
|
||||
| Connexions PostgreSQL | `docker exec postgres psql -U glibredecision -c "SELECT count(*) FROM pg_stat_activity;"` | > 80 |
|
||||
| Taille base de donnees | `docker exec postgres psql -U glibredecision -c "SELECT pg_size_pretty(pg_database_size('glibredecision'));"` | Information |
|
||||
| Statut IPFS | `docker exec ipfs ipfs id` | Erreur |
|
||||
|
||||
## Sauvegarde PostgreSQL
|
||||
|
||||
### Sauvegarde manuelle
|
||||
|
||||
```bash
|
||||
# Dump complet de la base
|
||||
docker compose -f docker/docker-compose.yml exec postgres \
|
||||
pg_dump -U glibredecision -Fc glibredecision > backup_$(date +%Y%m%d_%H%M%S).dump
|
||||
```
|
||||
|
||||
### Restauration
|
||||
|
||||
```bash
|
||||
# Restaurer un dump
|
||||
docker compose -f docker/docker-compose.yml exec -T postgres \
|
||||
pg_restore -U glibredecision -d glibredecision --clean < backup_20260228_120000.dump
|
||||
```
|
||||
|
||||
### Sauvegarde automatique (cron)
|
||||
|
||||
Ajoutez un crontab pour des sauvegardes quotidiennes :
|
||||
|
||||
```bash
|
||||
# Editer le crontab
|
||||
crontab -e
|
||||
|
||||
# Ajouter une sauvegarde quotidienne a 3h du matin
|
||||
0 3 * * * cd /opt/glibredecision && docker compose -f docker/docker-compose.yml exec -T postgres pg_dump -U glibredecision -Fc glibredecision > /opt/backups/glibredecision_$(date +\%Y\%m\%d).dump && find /opt/backups -name "glibredecision_*.dump" -mtime +30 -delete
|
||||
```
|
||||
|
||||
Cette commande :
|
||||
1. Execute un dump quotidien a 3h du matin
|
||||
2. Stocke les sauvegardes dans `/opt/backups/`
|
||||
3. Supprime automatiquement les sauvegardes de plus de 30 jours
|
||||
|
||||
## Mise a jour
|
||||
|
||||
### Procedure standard
|
||||
|
||||
```bash
|
||||
cd /opt/glibredecision
|
||||
|
||||
# 1. Tirer les dernieres images
|
||||
docker compose -f docker/docker-compose.yml pull
|
||||
|
||||
# 2. Redemarrer les services avec les nouvelles images
|
||||
docker compose -f docker/docker-compose.yml up -d --remove-orphans
|
||||
|
||||
# 3. Appliquer les migrations de base de donnees
|
||||
docker compose -f docker/docker-compose.yml exec backend alembic upgrade head
|
||||
|
||||
# 4. Nettoyer les anciennes images
|
||||
docker image prune -f
|
||||
|
||||
# 5. Verifier le deploiement
|
||||
docker compose -f docker/docker-compose.yml ps
|
||||
curl -s https://glibredecision.org/api/health
|
||||
```
|
||||
|
||||
### Pipeline CI/CD (Woodpecker)
|
||||
|
||||
La pipeline Woodpecker CI automatise le deploiement lors d'un push sur `main` :
|
||||
|
||||
1. **test-backend** : execution des tests Python (`pytest`)
|
||||
2. **test-frontend** : build du frontend Nuxt (`npm run build`)
|
||||
3. **docker-backend** : construction et push de l'image Docker backend
|
||||
4. **docker-frontend** : construction et push de l'image Docker frontend
|
||||
5. **deploy** : connexion SSH au serveur, pull des nouvelles images, redemarrage
|
||||
|
||||
Les secrets CI sont configures dans l'interface Woodpecker :
|
||||
|
||||
| Secret | Description |
|
||||
| ------ | ----------- |
|
||||
| `docker_registry` | URL du registre Docker |
|
||||
| `docker_username` | Identifiant du registre |
|
||||
| `docker_password` | Mot de passe du registre |
|
||||
| `deploy_host` | Adresse du serveur de production |
|
||||
| `deploy_username` | Utilisateur SSH |
|
||||
| `deploy_key` | Cle privee SSH |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Le backend ne demarre pas
|
||||
|
||||
**Symptome** : Le conteneur backend redemoarre en boucle.
|
||||
|
||||
```bash
|
||||
# Verifier les logs
|
||||
docker compose -f docker/docker-compose.yml logs backend
|
||||
|
||||
# Causes courantes :
|
||||
# 1. DATABASE_URL incorrecte -> verifier .env
|
||||
# 2. PostgreSQL pas encore pret -> verifier le health check
|
||||
# 3. Migrations non appliquees -> executer alembic upgrade head
|
||||
```
|
||||
|
||||
### Erreur de connexion a PostgreSQL
|
||||
|
||||
**Symptome** : `connection refused` ou `password authentication failed`.
|
||||
|
||||
```bash
|
||||
# Verifier que PostgreSQL est sain
|
||||
docker compose -f docker/docker-compose.yml exec postgres pg_isready
|
||||
|
||||
# Verifier les variables d'environnement
|
||||
docker compose -f docker/docker-compose.yml exec backend env | grep DATABASE
|
||||
|
||||
# Reinitialiser le mot de passe si necessaire (attention : destructif)
|
||||
docker compose -f docker/docker-compose.yml down -v # supprime les volumes
|
||||
docker compose -f docker/docker-compose.yml up -d # recree avec le nouveau mot de passe
|
||||
```
|
||||
|
||||
### Certificat TLS non genere
|
||||
|
||||
**Symptome** : Le site est inaccessible en HTTPS ou affiche un certificat invalide.
|
||||
|
||||
1. Verifier que le DNS A/AAAA pointe vers le serveur : `dig glibredecision.org`
|
||||
2. Verifier que les ports 80 et 443 sont ouverts : `ss -tlnp | grep -E '80|443'`
|
||||
3. Consulter les logs Traefik : `docker logs traefik 2>&1 | grep -i acme`
|
||||
|
||||
### IPFS ne repond pas
|
||||
|
||||
**Symptome** : Erreur lors de l'archivage dans le Sanctuaire.
|
||||
|
||||
```bash
|
||||
# Verifier le statut du noeud IPFS
|
||||
docker compose -f docker/docker-compose.yml exec ipfs ipfs id
|
||||
|
||||
# Verifier l'espace disque disponible
|
||||
docker compose -f docker/docker-compose.yml exec ipfs df -h /data/ipfs
|
||||
|
||||
# Redemarrer le noeud IPFS
|
||||
docker compose -f docker/docker-compose.yml restart ipfs
|
||||
```
|
||||
|
||||
### Erreur WebSocket
|
||||
|
||||
**Symptome** : L'indicateur de connexion temps reel est rouge.
|
||||
|
||||
1. Verifier que Traefik supporte les WebSockets (actif par defaut)
|
||||
2. Verifier le routage : le WebSocket est sur `/api/v1/ws`
|
||||
3. Verifier les logs backend pour les erreurs de connexion WebSocket
|
||||
278
docs/content/dev/9.security.md
Normal file
278
docs/content/dev/9.security.md
Normal file
@@ -0,0 +1,278 @@
|
||||
---
|
||||
title: Securite
|
||||
description: Politique de securite et mesures de protection de Glibredecision
|
||||
---
|
||||
|
||||
# Securite
|
||||
|
||||
Ce document decrit les mesures de securite implementees dans Glibredecision pour proteger l'integrite de la plateforme, des votes et des donnees des utilisateurs.
|
||||
|
||||
## Authentification Duniter V2 (Ed25519 challenge-response)
|
||||
|
||||
### Principe
|
||||
|
||||
Glibredecision n'utilise ni mot de passe ni systeme d'inscription classique. L'authentification repose entierement sur la cryptographie Ed25519 de la blockchain Duniter V2.
|
||||
|
||||
### Flux challenge-response
|
||||
|
||||
```
|
||||
Client Serveur
|
||||
| |
|
||||
|-- POST /auth/challenge ----------->|
|
||||
| { address: "5Grw..." } |
|
||||
| |-- Genere challenge (64 hex)
|
||||
| |-- Stocke en memoire (TTL 5 min)
|
||||
|<-------- { challenge: "a1b2..." } -|
|
||||
| |
|
||||
|-- Signe le challenge localement |
|
||||
| (cle privee Ed25519) |
|
||||
| |
|
||||
|-- POST /auth/verify ------------->|
|
||||
| { address, challenge, signature}|
|
||||
| |-- Verifie signature Ed25519
|
||||
| |-- Verifie identite WoT
|
||||
| |-- Cree/retrouve DuniterIdentity
|
||||
| |-- Genere token de session
|
||||
|<-------- { token: "..." } --------|
|
||||
```
|
||||
|
||||
### Garanties de securite
|
||||
|
||||
| Propriete | Mecanisme |
|
||||
| --------- | --------- |
|
||||
| **Cle privee jamais transmise** | Seule la signature est envoyee, pas la cle |
|
||||
| **Anti-replay** | Chaque challenge est usage unique, expire apres 5 minutes |
|
||||
| **Anti-interception** | HTTPS/TLS obligatoire en production |
|
||||
| **Identite verifiee** | L'adresse SS58 est verifiee sur la blockchain via `substrate-interface` |
|
||||
|
||||
### Verification de la signature
|
||||
|
||||
```python
|
||||
from substrateinterface import Keypair
|
||||
|
||||
keypair = Keypair(ss58_address=address)
|
||||
is_valid = keypair.verify(challenge_bytes, signature_bytes)
|
||||
```
|
||||
|
||||
La cle publique est derivee de l'adresse SS58 sans aucun appel reseau. La verification est locale et instantanee.
|
||||
|
||||
## Integrite des votes
|
||||
|
||||
### Signature cryptographique des votes
|
||||
|
||||
Chaque vote soumis est accompagne d'une **signature Ed25519** qui garantit son authenticite et son integrite.
|
||||
|
||||
### Payload signe
|
||||
|
||||
Le payload signe contient :
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid-de-la-session",
|
||||
"vote_value": "for",
|
||||
"timestamp": "2026-02-28T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Ce payload est signe par la cle privee du votant. La signature est stockee en base de donnees avec le vote, permettant une verification independante a tout moment.
|
||||
|
||||
### Proprietes garanties
|
||||
|
||||
| Propriete | Description |
|
||||
| --------- | ----------- |
|
||||
| **Authenticite** | Seul le proprietaire de l'adresse Duniter peut soumettre un vote en son nom |
|
||||
| **Integrite** | Le payload ne peut pas etre modifie apres signature sans invalider la signature |
|
||||
| **Non-repudiation** | Le votant ne peut pas nier avoir vote ; la preuve cryptographique est publique |
|
||||
| **Transparence** | Les votes signes sont publics et verifiables par quiconque |
|
||||
|
||||
### Verification d'un vote
|
||||
|
||||
```python
|
||||
from substrateinterface import Keypair
|
||||
|
||||
keypair = Keypair(ss58_address=voter_address)
|
||||
is_valid = keypair.verify(signed_payload.encode(), signature_bytes)
|
||||
```
|
||||
|
||||
### Protection contre la modification
|
||||
|
||||
Quand un votant modifie son vote, l'ancien vote est marque `is_active = false` mais conserve en base. Les deux votes (ancien et nouveau) conservent leur signature. L'historique complet est auditable.
|
||||
|
||||
## Rate limiting
|
||||
|
||||
### Limites par endpoint
|
||||
|
||||
Pour prevenir les abus et les attaques par deni de service, des limites de taux sont appliquees :
|
||||
|
||||
| Categorie | Endpoints | Limite | Fenetre |
|
||||
| --------- | --------- | ------ | ------- |
|
||||
| Authentification | `/auth/challenge`, `/auth/verify` | 10 requetes | 1 minute |
|
||||
| Vote | `/votes/sessions/{id}/vote` | 5 requetes | 1 minute |
|
||||
| Ecriture | `POST`, `PUT`, `DELETE` | 30 requetes | 1 minute |
|
||||
| Lecture | `GET` | 200 requetes | 1 minute |
|
||||
| WebSocket | `/ws` | 3 connexions | simultanees par IP |
|
||||
|
||||
### Reponse en cas de depassement
|
||||
|
||||
Le serveur retourne un code HTTP **429 Too Many Requests** avec un header `Retry-After` indiquant le temps d'attente en secondes.
|
||||
|
||||
## En-tetes de securite
|
||||
|
||||
Les en-tetes HTTP suivants sont configures en production :
|
||||
|
||||
| En-tete | Valeur | Description |
|
||||
| ------- | ------ | ----------- |
|
||||
| `Strict-Transport-Security` | `max-age=63072000; includeSubDomains; preload` | Force HTTPS pendant 2 ans, inclut les sous-domaines |
|
||||
| `Content-Security-Policy` | `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' wss:; img-src 'self' data: https://ipfs.io` | Restreint les sources de contenu autorisees |
|
||||
| `X-Content-Type-Options` | `nosniff` | Empeche le navigateur de deviner le type MIME |
|
||||
| `X-Frame-Options` | `DENY` | Empeche l'inclusion dans un iframe (anti-clickjacking) |
|
||||
| `X-XSS-Protection` | `1; mode=block` | Active la protection XSS du navigateur |
|
||||
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limite les informations de referer |
|
||||
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | Desactive les APIs sensibles non necessaires |
|
||||
|
||||
### CSP detaillee
|
||||
|
||||
La Content Security Policy est configuree pour :
|
||||
|
||||
- Autoriser les scripts uniquement depuis l'origine (`'self'`)
|
||||
- Autoriser les styles inline (necessaires pour UnoCSS)
|
||||
- Autoriser les connexions WebSocket (`wss:`)
|
||||
- Autoriser les images depuis IPFS gateway (`https://ipfs.io`) pour l'affichage des contenus archives
|
||||
- Bloquer tout le reste
|
||||
|
||||
## Sanctuaire : triple preuve d'integrite
|
||||
|
||||
### Chaine de verification
|
||||
|
||||
```
|
||||
Contenu --> [SHA-256] --> hash
|
||||
|
|
||||
+---> [IPFS] --> CID (content-addressable)
|
||||
|
|
||||
+---> [system.remark on-chain] --> preuve horodatee
|
||||
|
|
||||
v
|
||||
Triple preuve :
|
||||
1. Hash local = hash enregistre (integrite)
|
||||
2. CID IPFS = contenu identique (distribution)
|
||||
3. Remark on-chain = hash confirme (immutabilite temporelle)
|
||||
```
|
||||
|
||||
### Garanties
|
||||
|
||||
| Preuve | Ce qu'elle garantit | Point de defaillance |
|
||||
| ------ | ------------------- | -------------------- |
|
||||
| SHA-256 | Le contenu n'a pas ete modifie | Aucun (mathematique) |
|
||||
| IPFS CID | Le contenu est distribue et adressable par contenu | Disponibilite des noeuds IPFS |
|
||||
| On-chain remark | Le hash existait a la date du bloc | Securite de la blockchain Duniter |
|
||||
|
||||
### Format du remark on-chain
|
||||
|
||||
```
|
||||
glibredecision:sanctuary:{content_hash_sha256}
|
||||
```
|
||||
|
||||
Le prefixe `glibredecision:sanctuary:` permet d'identifier les ancrages de Glibredecision parmi tous les remarks de la blockchain.
|
||||
|
||||
## WebSocket : authentification et securite
|
||||
|
||||
### Authentification par token
|
||||
|
||||
La connexion WebSocket est authentifiee via le token de session obtenu lors du challenge-response :
|
||||
|
||||
```
|
||||
ws://server/api/v1/ws?token={session_token}
|
||||
```
|
||||
|
||||
Le serveur verifie le token avant d'accepter la connexion. Les connexions non authentifiees sont rejetees.
|
||||
|
||||
### Protections WebSocket
|
||||
|
||||
| Protection | Description |
|
||||
| ---------- | ----------- |
|
||||
| Token valide requis | Pas de connexion anonyme |
|
||||
| Limite de connexions | Maximum 3 connexions simultanees par IP |
|
||||
| Heartbeat | Ping/pong periodique pour detecter les connexions mortes |
|
||||
| Taille maximale des messages | Limite a 64 Ko pour prevenir les abus |
|
||||
| Broadcast read-only | Les clients recoivent les mises a jour mais ne peuvent pas modifier l'etat via WebSocket |
|
||||
|
||||
## Session management
|
||||
|
||||
### Tokens de session
|
||||
|
||||
| Propriete | Valeur |
|
||||
| --------- | ------ |
|
||||
| Duree de vie (TTL) | 24 heures |
|
||||
| Stockage serveur | Hash SHA-256 du token en base (table `sessions`) |
|
||||
| Stockage client | Token en clair dans le `localStorage` du navigateur |
|
||||
| Invalidation | Suppression de l'entree en base via `/auth/logout` |
|
||||
|
||||
### Securite des tokens
|
||||
|
||||
- Le token est genere avec un generateur cryptographiquement sur (CSPRNG)
|
||||
- Seul le **hash** du token est stocke en base de donnees. Si la base est compromise, les tokens bruts ne sont pas exposes.
|
||||
- A chaque requete authentifiee, le token fourni est hashe et compare au hash en base
|
||||
- Les tokens expires sont nettoyes periodiquement
|
||||
|
||||
### Deconnexion
|
||||
|
||||
L'appel a `POST /auth/logout` invalide la session cote serveur en supprimant l'entree de la table `sessions`. Le client supprime le token de son `localStorage`.
|
||||
|
||||
## Audit logging
|
||||
|
||||
### Evenements traces
|
||||
|
||||
Les actions suivantes sont enregistrees pour auditabilite :
|
||||
|
||||
| Evenement | Donnees enregistrees |
|
||||
| --------- | -------------------- |
|
||||
| Authentification reussie | Adresse SS58, timestamp, IP |
|
||||
| Authentification echouee | Adresse SS58, raison, timestamp, IP |
|
||||
| Vote soumis | Session ID, voter ID, vote, signature, timestamp |
|
||||
| Vote modifie | Session ID, voter ID, ancien vote (desactive), nouveau vote |
|
||||
| Decision creee/avancee | Decision ID, auteur, action, timestamp |
|
||||
| Document archive | Document ID, hash, CID, tx_hash |
|
||||
| Session de vote cloturee | Session ID, resultat, seuils |
|
||||
| Mandat assigne/revoque | Mandate ID, mandataire, action |
|
||||
|
||||
### Conservation
|
||||
|
||||
Les logs d'audit sont conserves de maniere permanente dans la base de donnees. Les votes et leurs signatures sont particulierement importants car ils constituent la preuve cryptographique des decisions collectives.
|
||||
|
||||
## Signalement de vulnerabilite (Responsible disclosure)
|
||||
|
||||
### Processus
|
||||
|
||||
Si vous decouvrez une vulnerabilite de securite dans Glibredecision, merci de suivre cette procedure de divulgation responsable :
|
||||
|
||||
1. **Ne divulguez pas publiquement** la vulnerabilite avant qu'un correctif soit disponible.
|
||||
2. **Contactez l'equipe** via le canal securise indique sur le depot Git Duniter ou via le forum Duniter (message prive aux mainteneurs).
|
||||
3. **Decrivez la vulnerabilite** avec autant de details que possible :
|
||||
- Type de vulnerabilite (injection, XSS, CSRF, contournement d'authentification, etc.)
|
||||
- Etapes pour reproduire
|
||||
- Impact potentiel
|
||||
- Suggestion de correctif (si applicable)
|
||||
4. **Delai de correction** : l'equipe s'engage a accuser reception sous 48 heures et a fournir un correctif sous 14 jours pour les vulnerabilites critiques.
|
||||
5. **Credit** : les chercheurs en securite qui signalent des vulnerabilites de maniere responsable seront credites dans le changelog (sauf s'ils preferent l'anonymat).
|
||||
|
||||
### Perimetre
|
||||
|
||||
Le perimetre de la politique de securite couvre :
|
||||
|
||||
| Inclus | Exclus |
|
||||
| ------ | ------ |
|
||||
| API backend (FastAPI) | Infrastructure d'hebergement tiers |
|
||||
| Frontend (Nuxt 4) | Blockchain Duniter V2 elle-meme |
|
||||
| Authentification challenge-response | Extension Polkadot.js |
|
||||
| Integrite des votes et signatures | Noeud IPFS (kubo) lui-meme |
|
||||
| WebSocket | Traefik |
|
||||
| Base de donnees (acces, injection) | -- |
|
||||
|
||||
### Exclusions
|
||||
|
||||
Les types de signalement suivants sont hors perimetre :
|
||||
|
||||
- Deni de service par volume (DDoS)
|
||||
- Ingenierie sociale
|
||||
- Attaques physiques sur l'infrastructure
|
||||
- Vulnerabilites dans les dependances tierces deja connues et trackees (utiliser les issues du depot)
|
||||
@@ -11,18 +11,39 @@ Bienvenue dans la documentation utilisateur de Glibredecision, la plateforme de
|
||||
|
||||
Glibredecision est une plateforme de gouvernance decentralisee qui permet aux membres de la Toile de Confiance (WoT) Duniter de :
|
||||
|
||||
- Gerer des **documents de reference** modulaires (Licence G1, Engagements Forgeron, etc.) sous vote permanent
|
||||
- Prendre des **decisions collectives** via des processus multi-etapes
|
||||
- **Voter** avec un systeme de seuil adaptatif base sur la participation
|
||||
- Attribuer des **mandats** a des membres de la communaute
|
||||
- **Archiver de maniere immuable** les decisions adoptees via IPFS et la blockchain Duniter
|
||||
- Gerer des **documents de reference** modulaires (Licence G1, Engagements Forgeron, Reglement du Comite Technique, etc.) sous vote permanent
|
||||
- Prendre des **decisions collectives** via des processus multi-etapes (qualification, examen, vote, execution, rapport)
|
||||
- **Voter** avec un systeme de seuil adaptatif base sur la participation : plus la participation est faible, plus le seuil est exigeant (mecanisme d'inertie)
|
||||
- Attribuer des **mandats** a des membres de la communaute via des elections formelles
|
||||
- **Archiver de maniere immuable** les decisions adoptees via IPFS et la blockchain Duniter (triple preuve SHA-256 + IPFS + on-chain)
|
||||
|
||||
## Sections
|
||||
La plateforme est entierement transparente : tous les votes sont publics, signes cryptographiquement et verifiables par quiconque.
|
||||
|
||||
- [Premiers pas](/user/getting-started) -- Connexion et prise en main
|
||||
- [Documents](/user/documents) -- Consulter et proposer des modifications aux documents de reference
|
||||
- [Decisions](/user/decisions) -- Comprendre et participer aux processus decisionnels
|
||||
- [Vote](/user/voting) -- Comment voter et comprendre les resultats
|
||||
- [Mandats](/user/mandates) -- Mandats et responsabilites
|
||||
- [Sanctuaire](/user/sanctuary) -- Archivage immuable et verification
|
||||
- [FAQ](/user/faq) -- Questions frequentes
|
||||
## Guides disponibles
|
||||
|
||||
| Guide | Description |
|
||||
| ----- | ----------- |
|
||||
| [Premiers pas](/user/getting-started) | Prerequis, premiere connexion, tour de l'interface, premier vote |
|
||||
| [Documents](/user/documents) | Consulter les documents de reference, proposer des modifications, vote permanent |
|
||||
| [Decisions](/user/decisions) | Comprendre et participer aux processus decisionnels multi-etapes |
|
||||
| [Vote](/user/voting) | Types de vote, formule de seuil expliquee, comment voter, jauge de seuil, simulateur |
|
||||
| [Mandats](/user/mandates) | Elections, candidatures, assignation, reporting, revocation |
|
||||
| [Sanctuaire](/user/sanctuary) | Archivage immuable, triple preuve, verification d'integrite |
|
||||
| [FAQ](/user/faq) | Reponses aux questions frequentes sur l'authentification, le vote, les documents, la securite |
|
||||
|
||||
## Par ou commencer ?
|
||||
|
||||
1. **Nouveau sur Glibredecision ?** Commencez par le guide [Premiers pas](/user/getting-started) pour vous connecter et decouvrir l'interface.
|
||||
2. **Vous voulez voter ?** Consultez le guide [Vote](/user/voting) pour comprendre les types de vote et la formule de seuil.
|
||||
3. **Vous voulez proposer une modification ?** Le guide [Documents](/user/documents) explique comment proposer des modifications aux textes fondateurs.
|
||||
4. **Une question ?** La [FAQ](/user/faq) repond aux questions les plus courantes.
|
||||
|
||||
## Contribuer a la documentation
|
||||
|
||||
Cette documentation est elle-meme un document en evolution. Si vous constatez une erreur, une imprecision ou un manque, vous pouvez :
|
||||
|
||||
- Ouvrir une issue sur le [depot Git](https://git.duniter.org/tools/glibredecision) de Glibredecision
|
||||
- Proposer une modification directement via une merge request
|
||||
- En discuter sur le [forum Duniter](https://forum.duniter.org)
|
||||
|
||||
La documentation est redigee en Markdown et fait partie du code source du projet (dossier `docs/`). Les contributions suivent le meme processus que le code : branche, merge request, revue.
|
||||
|
||||
@@ -5,6 +5,29 @@ description: Connexion et prise en main de Glibredecision
|
||||
|
||||
# Premiers pas
|
||||
|
||||
Ce guide vous accompagne de votre premiere visite jusqu'a votre premier vote sur Glibredecision.
|
||||
|
||||
## Prerequis
|
||||
|
||||
Avant de commencer, assurez-vous de disposer de :
|
||||
|
||||
| Prerequis | Description | Ou l'obtenir |
|
||||
| --------- | ----------- | ------------ |
|
||||
| **Navigateur moderne** | Chrome, Firefox, Edge ou Safari a jour | Mis a jour automatiquement |
|
||||
| **Extension Polkadot.js** | Extension de signature pour Substrate/Duniter V2 | [polkadot.js.org/extension](https://polkadot.js.org/extension/) |
|
||||
| **Identite Duniter V2** | Adresse SS58 avec une identite confirmee dans la Toile de Confiance | Via Cesium2 ou directement sur la blockchain Duniter V2 |
|
||||
|
||||
::callout{type="info"}
|
||||
Vous pouvez **consulter** les documents, decisions et resultats de vote sans aucune authentification. Seules les actions de participation (voter, proposer, creer) necessitent une identite Duniter.
|
||||
::
|
||||
|
||||
### Installer l'extension Polkadot.js
|
||||
|
||||
1. Rendez-vous sur [polkadot.js.org/extension](https://polkadot.js.org/extension/).
|
||||
2. Installez l'extension pour votre navigateur (Chrome ou Firefox).
|
||||
3. Creez ou importez votre compte Duniter V2 dans l'extension.
|
||||
4. Assurez-vous que votre adresse SS58 est bien celle liee a votre identite Duniter.
|
||||
|
||||
## Qui peut utiliser Glibredecision ?
|
||||
|
||||
Glibredecision est ouvert a tous les membres de la Toile de Confiance (WoT) Duniter V2. Pour utiliser pleinement la plateforme, vous devez posseder une identite Duniter avec une adresse SS58 valide.
|
||||
@@ -12,28 +35,60 @@ Glibredecision est ouvert a tous les membres de la Toile de Confiance (WoT) Duni
|
||||
- **Consultation** : tout visiteur peut consulter les documents, decisions et resultats de vote.
|
||||
- **Participation** (voter, proposer) : reservee aux membres authentifies via leur identite Duniter.
|
||||
|
||||
## Connexion
|
||||
## Premiere connexion
|
||||
|
||||
La connexion utilise votre identite Duniter sans jamais transmettre votre cle privee :
|
||||
La connexion utilise votre identite Duniter sans jamais transmettre votre cle privee. Le mecanisme est un **challenge-response** cryptographique :
|
||||
|
||||
### Comment ca marche (en termes simples)
|
||||
|
||||
Imaginez que la plateforme vous montre une phrase aleatoire et vous demande de la signer avec votre cle privee. C'est comme signer un document avec un stylo que vous seul possedez. La plateforme peut verifier que c'est bien votre signature grace a votre cle publique, sans jamais voir votre cle privee.
|
||||
|
||||
### Etape par etape
|
||||
|
||||
1. Cliquez sur **Se connecter** dans la barre de navigation.
|
||||
2. Saisissez votre **adresse Duniter** (format SS58, par exemple `5GrwvaEF...`).
|
||||
3. La plateforme vous envoie un **challenge** (texte aleatoire a signer).
|
||||
4. Signez le challenge avec votre cle privee Ed25519 (via votre portefeuille Duniter ou Cesium).
|
||||
5. Soumettez la signature. La plateforme verifie que vous etes bien le proprietaire de l'adresse.
|
||||
6. Vous etes connecte. Un jeton de session est stocke localement (valable 24h).
|
||||
3. La plateforme vous envoie un **challenge** : un texte aleatoire de 64 caracteres hexadecimaux.
|
||||
4. Votre extension Polkadot.js (ou votre portefeuille Cesium) vous demande d'autoriser la signature du challenge avec votre cle privee Ed25519.
|
||||
5. Signez le challenge. Votre cle privee ne quitte jamais votre appareil.
|
||||
6. Soumettez la signature. La plateforme verifie que vous etes bien le proprietaire de l'adresse.
|
||||
7. Vous etes connecte. Un jeton de session est stocke localement (valable 24 heures).
|
||||
|
||||
## Navigation
|
||||
::callout{type="tip"}
|
||||
Votre cle privee n'est **jamais** transmise au serveur. Seule la signature du challenge est envoyee. C'est le principe fondamental de l'authentification par challenge-response Ed25519.
|
||||
::
|
||||
|
||||
L'interface est organisee autour de cinq sections principales :
|
||||
## Tour de l'interface
|
||||
|
||||
| Section | Description |
|
||||
| ------------ | ---------------------------------------------------- |
|
||||
| Documents | Documents de reference de la communaute |
|
||||
| Decisions | Processus decisionnels en cours et archives |
|
||||
| Votes | Sessions de vote actives et resultats |
|
||||
| Mandats | Mandats attribues aux membres |
|
||||
| Sanctuaire | Archives immuables (IPFS + blockchain) |
|
||||
### Barre de navigation
|
||||
|
||||
La barre de navigation en haut de page contient :
|
||||
|
||||
- **Logo Glibredecision** : retour a l'accueil
|
||||
- **Menu principal** : acces aux cinq sections
|
||||
- **Bouton de connexion** / **Votre profil** (si connecte)
|
||||
- **Indicateur temps reel** : point colore indiquant l'etat de la connexion WebSocket
|
||||
|
||||
### Sidebar (menu lateral)
|
||||
|
||||
La sidebar sur la gauche donne acces aux cinq sections principales :
|
||||
|
||||
| Section | Icone | Description |
|
||||
| ------------ | ----- | ---------------------------------------------------- |
|
||||
| Documents | -- | Documents de reference de la communaute |
|
||||
| Decisions | -- | Processus decisionnels en cours et archives |
|
||||
| Votes | -- | Sessions de vote actives et resultats |
|
||||
| Mandats | -- | Mandats attribues aux membres |
|
||||
| Sanctuaire | -- | Archives immuables (IPFS + blockchain) |
|
||||
|
||||
### Dashboard (tableau de bord)
|
||||
|
||||
Apres connexion, le tableau de bord affiche un apercu rapide de :
|
||||
|
||||
- **Votes en cours** : les sessions de vote ouvertes auxquelles vous pouvez participer
|
||||
- **Vos derniers votes** : historique de vos votes recents
|
||||
- **Decisions actives** : les processus decisionnels en cours
|
||||
- **Mandats** : les mandats actifs et en cours d'election
|
||||
- **Activite recente** : flux des dernieres actions sur la plateforme
|
||||
|
||||
## Votre profil
|
||||
|
||||
@@ -46,6 +101,81 @@ Apres connexion, votre profil affiche :
|
||||
|
||||
Ces informations sont synchronisees depuis la blockchain Duniter V2 et determinent vos droits de vote.
|
||||
|
||||
## Premier vote : voter sur un item de document
|
||||
|
||||
Voici comment participer a votre premier vote en quelques minutes :
|
||||
|
||||
### 1. Trouver un vote ouvert
|
||||
|
||||
- Depuis le tableau de bord, consultez la section **Votes en cours**.
|
||||
- Ou rendez-vous dans la section **Votes** du menu et filtrez par statut "En cours".
|
||||
- Les sessions ouvertes sont signalees par un badge vert.
|
||||
|
||||
### 2. Lire le sujet
|
||||
|
||||
- Cliquez sur la session de vote qui vous interesse.
|
||||
- Lisez attentivement le texte soumis au vote (document, decision, modification d'item).
|
||||
- Consultez le diff si c'est une modification : les ajouts sont en vert, les suppressions en rouge.
|
||||
|
||||
### 3. Voter
|
||||
|
||||
- **Vote binaire** : cliquez sur **Pour** (vert) ou **Contre** (rouge).
|
||||
- **Vote nuance** : choisissez un niveau de 0 (CONTRE) a 5 (TOUT A FAIT) sur l'echelle proposee.
|
||||
- Ajoutez un **commentaire** si vous souhaitez expliquer votre choix (optionnel mais recommande).
|
||||
|
||||
### 4. Signer votre vote
|
||||
|
||||
- Apres avoir choisi, la plateforme genere un payload contenant votre vote, l'identifiant de la session et un horodatage.
|
||||
- Votre extension Polkadot.js vous demande de signer ce payload.
|
||||
- Signez, puis cliquez sur **Soumettre**.
|
||||
|
||||
### 5. Verification
|
||||
|
||||
- Un message de confirmation apparait.
|
||||
- Votre vote est visible dans la liste des votes de la session.
|
||||
- La jauge de seuil se met a jour en temps reel pour refleter votre vote.
|
||||
|
||||
::callout{type="info"}
|
||||
Vous pouvez modifier votre vote a tout moment tant que la session est ouverte. L'ancien vote est conserve pour l'audit mais seul le dernier compte.
|
||||
::
|
||||
|
||||
## Premiers pas avec les decisions
|
||||
|
||||
Au-dela du vote, vous pouvez participer activement a la gouvernance :
|
||||
|
||||
### Proposer une modification de document
|
||||
|
||||
1. Ouvrez un document de reference dans la section **Documents**.
|
||||
2. Selectionnez l'item (clause, regle, article) que vous souhaitez modifier.
|
||||
3. Cliquez sur **Proposer une modification**.
|
||||
4. Redigez votre nouveau texte et justifiez votre proposition.
|
||||
5. Soumettez : un diff est genere automatiquement.
|
||||
|
||||
Votre proposition sera examinee et soumise au vote par la communaute.
|
||||
|
||||
### Creer une decision
|
||||
|
||||
1. Rendez-vous dans la section **Decisions**.
|
||||
2. Cliquez sur **Nouvelle decision**.
|
||||
3. Renseignez le titre, la description et le contexte.
|
||||
4. Choisissez le type de decision et le protocole de vote.
|
||||
5. Definissez les etapes du processus.
|
||||
|
||||
### Consulter le Sanctuaire
|
||||
|
||||
Le Sanctuaire contient les archives immuables de toutes les decisions adoptees, documents archives et resultats de vote. Rendez-vous dans la section **Sanctuaire** pour explorer l'historique verifiable de la communaute.
|
||||
|
||||
## Deconnexion
|
||||
|
||||
Cliquez sur votre profil puis **Se deconnecter**. La session est invalidee cote serveur et le jeton local est supprime.
|
||||
|
||||
## Pour aller plus loin
|
||||
|
||||
| Guide | Description |
|
||||
| ----- | ----------- |
|
||||
| [Documents](/user/documents) | Tout savoir sur les documents de reference et leurs modifications |
|
||||
| [Decisions](/user/decisions) | Comprendre les processus decisionnels multi-etapes |
|
||||
| [Vote](/user/voting) | Comprendre les types de vote, la formule de seuil et le simulateur |
|
||||
| [Mandats](/user/mandates) | Elections et responsabilites au sein de la communaute |
|
||||
| [Sanctuaire](/user/sanctuary) | Archivage immuable et verification d'integrite |
|
||||
| [FAQ](/user/faq) | Reponses aux questions frequentes |
|
||||
|
||||
@@ -5,9 +5,11 @@ description: Guide des documents de reference sur Glibredecision
|
||||
|
||||
# Documents de reference
|
||||
|
||||
## Principe
|
||||
## Qu'est-ce qu'un document de reference ?
|
||||
|
||||
Les documents de reference sont les textes fondateurs de la communaute Duniter/G1. Ils sont **modulaires** : chaque document est compose d'items individuels (clauses, regles, verifications, preambules, sections) qui peuvent etre modifies independamment par proposition et vote.
|
||||
Un document de reference est un **texte fondateur** de la communaute Duniter/G1. Il peut s'agir d'une licence monetaire, d'un engagement que les membres s'engagent a respecter, d'un reglement interieur ou d'un texte constitutif. Ces documents definissent les regles, les valeurs et le fonctionnement de la communaute.
|
||||
|
||||
Ce qui rend Glibredecision unique, c'est que ces documents sont **modulaires** et sous **vote permanent** : chaque document est compose d'items individuels (clauses, regles, verifications, preambules, sections) qui peuvent etre modifies independamment par proposition et vote. La communaute peut faire evoluer ses textes de maniere continue, sans procedure lourde ni periode speciale.
|
||||
|
||||
## Types de documents
|
||||
|
||||
@@ -18,6 +20,38 @@ Les documents de reference sont les textes fondateurs de la communaute Duniter/G
|
||||
| Reglement | Reglement interieur d'un organe | Reglement du Comite Technique |
|
||||
| Constitution | Texte constitutif fondamental | -- |
|
||||
|
||||
## Structure : Document, Items et Versions
|
||||
|
||||
Un document est organise selon une structure a trois niveaux :
|
||||
|
||||
```
|
||||
Document (ex: Licence G1 v2.0.0)
|
||||
|
|
||||
+-- Item 1 (clause 1 : Preambule)
|
||||
| |-- Version 1.0 (texte courant)
|
||||
| |-- Version 1.1 (proposition en attente)
|
||||
|
|
||||
+-- Item 2 (regle 2.1 : Conditions d'adhesion)
|
||||
| |-- Version 1.0 (texte courant)
|
||||
|
|
||||
+-- Item 3 (verification 3.1 : Distance rule)
|
||||
|-- Version 1.0 (texte courant)
|
||||
|-- Version 1.1 (proposition rejetee)
|
||||
|-- Version 1.2 (proposition en vote)
|
||||
```
|
||||
|
||||
### Document
|
||||
|
||||
Le document est le conteneur. Il possede un titre, un type, un numero de version semantique (ex: `2.0.0`), un statut et une description.
|
||||
|
||||
### Item
|
||||
|
||||
Chaque item est une unite modulaire du document : une clause, une regle, une verification, un preambule ou une section. Chaque item a une position hierarchique (ex: "1", "1.1", "3.2") et un texte courant.
|
||||
|
||||
### Version
|
||||
|
||||
Chaque modification proposee a un item cree une nouvelle version. La version contient le texte propose, un diff automatique par rapport au texte courant, et la justification de l'auteur. Les versions suivent un cycle de vie : proposee, en vote, acceptee ou rejetee.
|
||||
|
||||
## Consulter un document
|
||||
|
||||
1. Rendez-vous dans la section **Documents**.
|
||||
@@ -53,6 +87,14 @@ La proposition cree une nouvelle **version** de l'item. Cette version passe ensu
|
||||
Plusieurs versions peuvent etre proposees simultanement pour un meme item. Lorsqu'une version est acceptee, toutes les autres versions en attente sont automatiquement rejetees.
|
||||
::
|
||||
|
||||
## Vote permanent sur les items
|
||||
|
||||
Les documents actifs sont sous **vote permanent** : il n'y a pas de periode speciale pour proposer des changements. A tout moment, un membre authentifie peut proposer une modification a n'importe quel item.
|
||||
|
||||
Chaque item peut avoir un **protocole de vote specifique** qui definit les parametres de seuil (duree, majorite, gradient, criteres Smith/TechComm). Si aucun protocole specifique n'est defini, le protocole par defaut du document s'applique.
|
||||
|
||||
Le vote permanent garantit que les textes fondateurs peuvent evoluer de maniere continue et organique, en refletant en permanence la volonte de la communaute.
|
||||
|
||||
## Examiner et accepter/rejeter une version
|
||||
|
||||
Les membres habilites (selon le protocole de vote associe) peuvent examiner les versions proposees :
|
||||
@@ -106,7 +148,7 @@ Le document est en vigueur et sous **vote permanent**. Tout membre authentifie p
|
||||
|
||||
### Archive (archived)
|
||||
|
||||
Le document a ete archive dans le **Sanctuaire**. Son contenu est fige et preservee de maniere immuable via :
|
||||
Le document a ete archive dans le **Sanctuaire**. Son contenu est fige et preserve de maniere immuable via :
|
||||
|
||||
- Un hash SHA-256 pour garantir l'integrite.
|
||||
- Un stockage sur IPFS pour la distribution decentralisee.
|
||||
@@ -114,6 +156,14 @@ Le document a ete archive dans le **Sanctuaire**. Son contenu est fige et preser
|
||||
|
||||
Un document archive ne peut plus etre modifie. Pour le consulter, rendez-vous dans la section Sanctuaire.
|
||||
|
||||
## Statuts des documents
|
||||
|
||||
| Statut | Description |
|
||||
| --------- | ------------------------------------------------ |
|
||||
| Brouillon | En cours de redaction, non soumis au vote |
|
||||
| Actif | Document en vigueur, sous vote permanent |
|
||||
| Archive | Document archive dans le Sanctuaire, plus modifiable |
|
||||
|
||||
## Archiver un document dans le Sanctuaire
|
||||
|
||||
Pour archiver un document actif (necessite une authentification) :
|
||||
@@ -132,14 +182,52 @@ Pour archiver un document actif (necessite une authentification) :
|
||||
L'archivage est une operation irreversible. Une fois archive, le document ne peut plus etre modifie.
|
||||
::
|
||||
|
||||
## Statuts des documents
|
||||
|
||||
| Statut | Description |
|
||||
| --------- | ------------------------------------------------ |
|
||||
| Brouillon | En cours de redaction, non soumis au vote |
|
||||
| Actif | Document en vigueur, sous vote permanent |
|
||||
| Archive | Document archive dans le Sanctuaire, plus modifiable |
|
||||
|
||||
## Versionnage
|
||||
|
||||
Chaque document possede un numero de version semantique (ex: `2.0.0`). Chaque modification adoptee peut entrainer une mise a jour de version selon l'importance du changement.
|
||||
|
||||
## Exemple concret : modifier un article de la Licence G1
|
||||
|
||||
Prenons un exemple complet de bout en bout. Vous souhaitez modifier la regle de distance (item 3.1) de la Licence G1 pour preciser une condition supplementaire.
|
||||
|
||||
### 1. Trouver l'item
|
||||
|
||||
- Rendez-vous dans **Documents** et ouvrez la **Licence G1**.
|
||||
- Faites defiler jusqu'a l'item **3.1 -- Distance rule** et cliquez dessus.
|
||||
|
||||
### 2. Consulter le texte courant
|
||||
|
||||
- Lisez le texte en vigueur et l'historique des versions precedentes.
|
||||
- Verifiez que votre modification n'a pas deja ete proposee par quelqu'un d'autre.
|
||||
|
||||
### 3. Proposer votre modification
|
||||
|
||||
- Cliquez sur **Proposer une modification**.
|
||||
- Redigez votre nouveau texte. Par exemple, ajoutez une precision sur le nombre de pas de distance autorise.
|
||||
- Dans le champ **Justification**, expliquez pourquoi : "La regle actuelle ne precise pas le cas ou un membre est a la limite exacte de la distance maximale. Cette modification clarifie que la distance est inclusive."
|
||||
- Soumettez votre proposition.
|
||||
|
||||
### 4. Le diff est genere
|
||||
|
||||
Le systeme genere automatiquement un diff montrant les differences :
|
||||
|
||||
```diff
|
||||
- Le membre doit respecter la regle de distance WoT.
|
||||
+ Le membre doit respecter la regle de distance WoT. La distance
|
||||
+ maximale est inclusive : un membre a exactement 5 pas est conforme.
|
||||
```
|
||||
|
||||
### 5. Examen et vote
|
||||
|
||||
- La communaute peut consulter votre proposition, lire votre justification et examiner le diff.
|
||||
- Si un processus de decision est lance, une session de vote est creee.
|
||||
- Les membres votent selon le protocole de vote associe a cet item.
|
||||
|
||||
### 6. Resultat
|
||||
|
||||
- **Si acceptee** : votre texte remplace le texte courant de l'item 3.1. Toutes les autres propositions en attente pour cet item sont automatiquement rejetees. Le numero de version du document peut etre mis a jour.
|
||||
- **Si rejetee** : le texte courant reste inchange. Votre proposition est archivee avec le statut "rejetee" pour transparence.
|
||||
|
||||
### 7. Archivage
|
||||
|
||||
Si la modification est suffisamment importante, le document mis a jour peut etre archive dans le Sanctuaire, creant une trace immuable de cette evolution.
|
||||
|
||||
@@ -19,20 +19,142 @@ Chaque votant choisit **Pour** ou **Contre**. Le seuil est calcule par la formul
|
||||
|
||||
Chaque votant exprime son opinion sur une echelle a 6 niveaux :
|
||||
|
||||
| Niveau | Label | Comptage |
|
||||
| ------ | ------------- | --------------- |
|
||||
| 0 | CONTRE | Negatif |
|
||||
| 1 | PAS DU TOUT | Negatif |
|
||||
| 2 | PAS D'ACCORD | Negatif |
|
||||
| 3 | NEUTRE | Positif |
|
||||
| 4 | D'ACCORD | Positif |
|
||||
| 5 | TOUT A FAIT | Positif |
|
||||
| Niveau | Label | Signification | Comptage |
|
||||
| ------ | ------------- | --------------------------------------------------- | -------- |
|
||||
| 0 | CONTRE | Opposition totale et ferme | Negatif |
|
||||
| 1 | PAS DU TOUT | Desaccord fort, points essentiels non remplis | Negatif |
|
||||
| 2 | PAS D'ACCORD | Desaccord modere, des reserves importantes | Negatif |
|
||||
| 3 | NEUTRE | Ni pour ni contre, ou acceptation sans enthousiasme | Positif |
|
||||
| 4 | D'ACCORD | Approbation avec eventuellement des reserves mineures | Positif |
|
||||
| 5 | TOUT A FAIT | Approbation totale et enthousiaste | Positif |
|
||||
|
||||
Le vote est adopte si les niveaux positifs (3, 4, 5) representent au moins 80% des votes et qu'un nombre minimum de participants est atteint.
|
||||
Le vote nuance est adopte si les niveaux positifs (3, 4, 5) representent au moins **80%** des votes et qu'un nombre minimum de participants est atteint (par defaut 59).
|
||||
|
||||
## Comment voter -- Vote binaire
|
||||
### Quand utiliser le vote nuance ?
|
||||
|
||||
### Etape par etape
|
||||
Le vote nuance est recommande pour :
|
||||
|
||||
- Les textes longs comportant de nombreux articles (les votants peuvent exprimer un accord partiel).
|
||||
- Les decisions ou la nuance est importante (budget, parametre technique).
|
||||
- Les cas ou il est utile de mesurer le degre d'adhesion, pas seulement le resultat binaire.
|
||||
|
||||
## La formule de seuil expliquee simplement
|
||||
|
||||
### L'analogie de l'inertie
|
||||
|
||||
Imaginez un gros rocher pose au sommet d'une colline. Pour le deplacer, il faut une force considerable : c'est l'**inertie**. Dans Glibredecision, le rocher represente le statu quo et la force necessaire represente le nombre de votes favorables.
|
||||
|
||||
- **Quand peu de personnes poussent** (faible participation) : il faut que presque tout le monde pousse dans la meme direction. Si seulement 10 personnes sur 7000 votent, il faut que 9 sur 10 soient pour.
|
||||
- **Quand beaucoup de personnes poussent** (forte participation) : la majorite simple suffit. Si 7000 personnes votent, il suffit que 3500 soient pour (50%).
|
||||
|
||||
Ce mecanisme empeche qu'un petit groupe prenne des decisions engageant toute la communaute, tout en permettant une gouvernance efficace quand la participation est large.
|
||||
|
||||
### La formule
|
||||
|
||||
La formule exacte est :
|
||||
|
||||
```
|
||||
Seuil = C + B^W + (M + (1-M) * (1 - (T/W)^G)) * max(0, T-C)
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
| Symbole | Signification | Exemple |
|
||||
| ------- | ------------- | ------- |
|
||||
| C | Base constante (plancher minimum) | 0 |
|
||||
| B | Exposant de base (negligeable pour grandes communautes) | 0.1 |
|
||||
| W | Taille de la Toile de Confiance (membres eligibles) | 7224 |
|
||||
| T | Nombre total de votes exprimes | 120 |
|
||||
| M | Ratio de majorite cible a pleine participation | 0.50 (50%) |
|
||||
| G | Gradient : vitesse de convergence vers la majorite | 0.2 |
|
||||
|
||||
### Exemple concret
|
||||
|
||||
Pour le vote de l'**Engagement Forgeron v2.0.0** :
|
||||
|
||||
- WoT = 7224 membres, 120 votes (1.7% de participation)
|
||||
- Parametres : M=50%, B=0.1, G=0.2, C=0
|
||||
- **Seuil calcule : 94 votes favorables requis** (soit 78% des votants)
|
||||
- Resultat : 97 pour, 23 contre -- **Adopte** (97 >= 94)
|
||||
|
||||
La faible participation a rendu le seuil exigeant : 78% au lieu de 50%. C'est l'inertie en action.
|
||||
|
||||
### Tableau d'inertie
|
||||
|
||||
Le tableau suivant montre comment l'exigence evolue avec la participation, pour les parametres de reference `M50 G.2` avec une WoT de 7224 :
|
||||
|
||||
| Participation | % de la WoT | % favorables requis |
|
||||
| ------------: | ----------: | ------------------: |
|
||||
| 10 | 0.1% | 87.4% |
|
||||
| 50 | 0.7% | 82.3% |
|
||||
| 100 | 1.4% | 80.1% |
|
||||
| 120 | 1.7% | 79.5% |
|
||||
| 200 | 2.8% | 77.7% |
|
||||
| 500 | 6.9% | 74.4% |
|
||||
| 1000 | 13.8% | 71.2% |
|
||||
| 2000 | 27.7% | 67.7% |
|
||||
| 5000 | 69.2% | 62.6% |
|
||||
| 7224 | 100% | 50.0% |
|
||||
|
||||
On constate que meme a 500 votants (6.9%), il faut encore 74.4% de votes favorables. L'inertie ne descend en dessous de 66% qu'au-dela de 2000 votants.
|
||||
|
||||
## Criteres additionnels
|
||||
|
||||
### Critere Smith (Forgerons)
|
||||
|
||||
Certaines decisions exigent un nombre minimum de votes favorables de la part des **forgerons** (membres Smith de la WoT). Ce critere garantit que les decisions qui affectent le reseau sont soutenues par ceux qui le maintiennent.
|
||||
|
||||
Le seuil Smith est calcule par : `ceil(SmithWotSize^S)` ou `S` est l'exposant Smith.
|
||||
|
||||
**Exemple** : Avec 20 forgerons et S=0.1, le seuil est `ceil(20^0.1) = ceil(1.35) = 2`. Il faut au minimum 2 votes favorables de forgerons.
|
||||
|
||||
### Critere TechComm (Comite Technique)
|
||||
|
||||
De maniere similaire, certaines decisions exigent un nombre minimum de votes favorables du **Comite Technique**. Cela concerne les decisions techniques (runtime upgrades, modifications d'infrastructure).
|
||||
|
||||
Le seuil TechComm est calcule par : `ceil(CoTecSize^T)` ou `T` est l'exposant TechComm.
|
||||
|
||||
**Exemple** : Avec 5 membres TechComm et T=0.1, le seuil est `ceil(5^0.1) = ceil(1.17) = 2`. Il faut au minimum 2 votes favorables du Comite Technique.
|
||||
|
||||
### Adoption finale
|
||||
|
||||
Un vote n'est adopte que si **les trois conditions** sont remplies simultanement :
|
||||
|
||||
1. Les votes favorables atteignent le seuil WoT (formule principale)
|
||||
2. Les votes favorables des forgerons atteignent le seuil Smith (si actif)
|
||||
3. Les votes favorables du Comite Technique atteignent le seuil TechComm (si actif)
|
||||
|
||||
## Mode params : decoder les parametres
|
||||
|
||||
Les parametres de formule sont encodes dans une chaine compacte pour faciliter la lecture. Voici comment decoder `"D30M50B.1G.2T.1"` :
|
||||
|
||||
| Code | Valeur | Signification |
|
||||
| ---- | ------ | ------------- |
|
||||
| D30 | 30 | Duree du vote : **30 jours** |
|
||||
| M50 | 50% | Majorite cible : **50%** (majorite simple a pleine participation) |
|
||||
| B.1 | 0.1 | Exposant de base : **0.1** (negligeable pour grandes WoT) |
|
||||
| G.2 | 0.2 | Gradient : **0.2** (convergence rapide vers la majorite) |
|
||||
| T.1 | 0.1 | Exposant TechComm : **0.1** (critere TechComm actif) |
|
||||
|
||||
Autres codes possibles :
|
||||
|
||||
| Code | Parametre | Exemple | Signification |
|
||||
| ---- | --------- | ------- | ------------- |
|
||||
| C | Base constante | C3 | Minimum 3 votes favorables quelle que soit la formule |
|
||||
| S | Exposant Smith | S.1 | Critere Smith actif avec exposant 0.1 |
|
||||
| N | Multiplicateur ratio | N1.5 | Multiplicateur 1.5 en mode ratio |
|
||||
| R | Mode ratio | R1 | Mode ratio active |
|
||||
|
||||
### Exemples de configurations
|
||||
|
||||
- `"D30M50B.1G.2"` : 30 jours, majorite 50%, configuration standard
|
||||
- `"D30M50B.1G.2S.1T.1"` : idem avec criteres Smith et TechComm
|
||||
- `"D60M66B.05G.3"` : 60 jours, super-majorite 66%, gradient plus strict
|
||||
- `"D14M50B.1G.1"` : 14 jours, gradient rapide (decisions urgentes)
|
||||
|
||||
## Comment voter : etapes concretes
|
||||
|
||||
### Vote binaire
|
||||
|
||||
1. **Acceder a la session de vote** : Rendez-vous dans la section **Votes** depuis le menu principal, ou accedez directement a la page d'une decision en cours. Les sessions ouvertes sont signalees par un badge vert "En cours".
|
||||
|
||||
@@ -48,6 +170,18 @@ Le vote est adopte si les niveaux positifs (3, 4, 5) representent au moins 80% d
|
||||
|
||||
6. **Confirmer la soumission** : Une fois la signature effectuee, cliquez sur **Soumettre**. Un message de confirmation apparait avec le resume de votre vote.
|
||||
|
||||
### Vote nuance
|
||||
|
||||
1. **Acceder a la session** : Meme procedure que pour le vote binaire. Les sessions de vote nuance sont identifiees par un badge "Nuance" en plus du badge de statut.
|
||||
|
||||
2. **Consulter le sujet** : Lisez le document ou la decision soumise au vote.
|
||||
|
||||
3. **Choisir votre niveau** : Le panneau de vote nuance affiche une echelle a 6 niveaux sous forme de curseur ou de boutons. Les niveaux 3, 4 et 5 sont comptes comme **positifs**. Les niveaux 0, 1 et 2 sont comptes comme **negatifs**.
|
||||
|
||||
4. **Ajouter un commentaire** (optionnel) : Particulierement utile pour les niveaux intermediaires (1, 2, 3, 4), afin d'expliquer vos reserves ou vos attentes.
|
||||
|
||||
5. **Signer et soumettre** : Meme procedure que pour le vote binaire.
|
||||
|
||||
### Modifier son vote
|
||||
|
||||
Tant que la session est ouverte, vous pouvez changer votre vote :
|
||||
@@ -58,39 +192,7 @@ Tant que la session est ouverte, vous pouvez changer votre vote :
|
||||
4. Selectionnez votre nouveau choix et signez a nouveau.
|
||||
5. L'ancien vote est desactive (conserve dans l'historique pour audit) et remplace par le nouveau.
|
||||
|
||||
## Comment voter -- Vote nuance
|
||||
|
||||
### Etape par etape
|
||||
|
||||
1. **Acceder a la session** : Meme procedure que pour le vote binaire. Les sessions de vote nuance sont identifiees par un badge "Nuance" en plus du badge de statut.
|
||||
|
||||
2. **Consulter le sujet** : Lisez le document ou la decision soumise au vote.
|
||||
|
||||
3. **Choisir votre niveau** : Le panneau de vote nuance affiche une echelle a 6 niveaux sous forme de curseur ou de boutons :
|
||||
|
||||
| Niveau | Label | Signification |
|
||||
| -----: | ------------- | ---------------------------------------------------------- |
|
||||
| 0 | CONTRE | Opposition totale et ferme |
|
||||
| 1 | PAS DU TOUT | Desaccord fort, points essentiels non remplis |
|
||||
| 2 | PAS D'ACCORD | Desaccord modere, des reserves importantes |
|
||||
| 3 | NEUTRE | Ni pour ni contre, ou acceptation sans enthousiasme |
|
||||
| 4 | D'ACCORD | Approbation avec eventuellement des reserves mineures |
|
||||
| 5 | TOUT A FAIT | Approbation totale et enthousiaste |
|
||||
|
||||
Les niveaux 3, 4 et 5 sont comptes comme **positifs**. Les niveaux 0, 1 et 2 sont comptes comme **negatifs**.
|
||||
|
||||
4. **Ajouter un commentaire** (optionnel) : Particulierement utile pour les niveaux intermediaires (1, 2, 3, 4), afin d'expliquer vos reserves ou vos attentes.
|
||||
|
||||
5. **Signer et soumettre** : Meme procedure que pour le vote binaire.
|
||||
|
||||
### Quand utiliser le vote nuance ?
|
||||
|
||||
Le vote nuance est recommande pour :
|
||||
- Les textes longs comportant de nombreux articles (les votants peuvent exprimer un accord partiel).
|
||||
- Les decisions ou la nuance est importante (budget, parametre technique).
|
||||
- Les cas ou il est utile de mesurer le degre d'adhesion, pas seulement le resultat binaire.
|
||||
|
||||
## Comprendre la jauge de seuil
|
||||
## Comprendre les resultats : la jauge de seuil
|
||||
|
||||
La page de chaque session de vote affiche une **jauge de seuil** qui represente visuellement l'etat du vote en temps reel.
|
||||
|
||||
@@ -123,6 +225,58 @@ En cliquant sur le bouton **Voir le detail** sous la jauge, une modale s'ouvre a
|
||||
- Les criteres Smith et TechComm si applicables.
|
||||
- Un lien vers le simulateur de formules pour experimenter d'autres scenarios.
|
||||
|
||||
### Page de resultat
|
||||
|
||||
La page de resultat affiche :
|
||||
|
||||
| Information | Description |
|
||||
| ------------------- | ---------------------------------------------------- |
|
||||
| Votes pour | Nombre de votes favorables |
|
||||
| Votes contre | Nombre de votes defavorables |
|
||||
| Total | Nombre total de votes exprimes |
|
||||
| Taille WoT | Nombre de membres WoT eligibles (snapshot au debut) |
|
||||
| Seuil requis | Seuil calcule par la formule d'inertie |
|
||||
| Critere Smith | Seuil et validation des votes Smith (si applicable) |
|
||||
| Critere TechComm | Seuil et validation des votes TechComm (si applicable) |
|
||||
| Resultat | **Adopte** ou **Rejete** |
|
||||
|
||||
## Simulateur de formules
|
||||
|
||||
Le simulateur de formules vous permet de tester le comportement du seuil d'adoption avec differentes configurations, sans creer de session de vote.
|
||||
|
||||
### Acceder au simulateur
|
||||
|
||||
1. Depuis le menu principal, selectionnez **Outils** puis **Simulateur de formules**.
|
||||
2. Vous pouvez aussi y acceder depuis le detail du calcul de seuil d'une session de vote (bouton **Ouvrir le simulateur**).
|
||||
|
||||
### Utiliser le simulateur
|
||||
|
||||
Le simulateur presente un formulaire avec les parametres ajustables :
|
||||
|
||||
| Parametre | Description | Curseur/Champ |
|
||||
| ----------------------- | ---------------------------------------------- | ------------- |
|
||||
| Taille WoT ($W$) | Nombre de membres eligibles | Curseur |
|
||||
| Total votes ($T$) | Nombre de votes exprimes | Curseur |
|
||||
| Majorite ($M$) | Pourcentage de majorite cible | Curseur |
|
||||
| Base ($B$) | Exposant de base | Champ |
|
||||
| Gradient ($G$) | Vitesse de convergence | Curseur |
|
||||
| Base constante ($C$) | Plancher minimum de votes | Champ |
|
||||
| Votes Pour | Nombre de votes favorables (pour tester l'adoption) | Curseur |
|
||||
|
||||
En ajustant les curseurs, le resultat se met a jour en temps reel :
|
||||
- Le **seuil calcule** est affiche.
|
||||
- Un graphique montre la courbe du seuil en fonction de la participation.
|
||||
- Le resultat **Adopte** / **Rejete** s'affiche en fonction des votes pour saisis.
|
||||
|
||||
### Exemple de scenario
|
||||
|
||||
Vous souhaitez comparer deux configurations pour un vote attendu avec environ 200 participants sur une WoT de 7224 :
|
||||
|
||||
1. Configuration actuelle `M50 G.2` : Seuil = 156 (77.7% requis).
|
||||
2. Configuration proposee `M50 G.4` : Seuil = 171 (85.5% requis).
|
||||
|
||||
Le simulateur montre visuellement l'impact : avec un gradient plus eleve, l'exigence est sensiblement plus forte a faible participation.
|
||||
|
||||
## Mises a jour en temps reel
|
||||
|
||||
Glibredecision utilise une connexion **WebSocket** pour diffuser les mises a jour de vote en temps reel a tous les utilisateurs qui consultent une session de vote.
|
||||
@@ -166,43 +320,6 @@ Sur la page d'une session de vote, l'onglet **Votes** affiche la liste de tous l
|
||||
|
||||
Les votes sont publics et verifiables par tous. Il n'y a pas de vote secret dans Glibredecision : la transparence est un principe fondamental.
|
||||
|
||||
## Simulateur de formules
|
||||
|
||||
Le simulateur de formules vous permet de tester le comportement du seuil d'adoption avec differentes configurations, sans creer de session de vote.
|
||||
|
||||
### Acceder au simulateur
|
||||
|
||||
1. Depuis le menu principal, selectionnez **Outils** puis **Simulateur de formules**.
|
||||
2. Vous pouvez aussi y acceder depuis le detail du calcul de seuil d'une session de vote (bouton **Ouvrir le simulateur**).
|
||||
|
||||
### Utiliser le simulateur
|
||||
|
||||
Le simulateur presente un formulaire avec les parametres ajustables :
|
||||
|
||||
| Parametre | Description | Curseur/Champ |
|
||||
| ----------------------- | ---------------------------------------------- | ------------- |
|
||||
| Taille WoT ($W$) | Nombre de membres eligibles | Curseur |
|
||||
| Total votes ($T$) | Nombre de votes exprimes | Curseur |
|
||||
| Majorite ($M$) | Pourcentage de majorite cible | Curseur |
|
||||
| Base ($B$) | Exposant de base | Champ |
|
||||
| Gradient ($G$) | Vitesse de convergence | Curseur |
|
||||
| Base constante ($C$) | Plancher minimum de votes | Champ |
|
||||
| Votes Pour | Nombre de votes favorables (pour tester l'adoption) | Curseur |
|
||||
|
||||
En ajustant les curseurs, le resultat se met a jour en temps reel :
|
||||
- Le **seuil calcule** est affiche.
|
||||
- Un graphique montre la courbe du seuil en fonction de la participation.
|
||||
- Le resultat **Adopte** / **Rejete** s'affiche en fonction des votes pour saisis.
|
||||
|
||||
### Exemple de scenario
|
||||
|
||||
Vous souhaitez comparer deux configurations pour un vote attendu avec environ 200 participants sur une WoT de 7224 :
|
||||
|
||||
1. Configuration actuelle `M50 G.2` : Seuil = 156 (77.7% requis).
|
||||
2. Configuration proposee `M50 G.4` : Seuil = 171 (85.5% requis).
|
||||
|
||||
Le simulateur montre visuellement l'impact : avec un gradient plus eleve, l'exigence est sensiblement plus forte a faible participation.
|
||||
|
||||
## Meta-gouvernance : voter sur les regles du vote
|
||||
|
||||
La meta-gouvernance est la capacite de **modifier les regles du systeme de vote en utilisant le systeme de vote lui-meme**. C'est le mecanisme par lequel la communaute garde le controle sur les parametres fondamentaux de la prise de decision.
|
||||
@@ -250,32 +367,6 @@ Un membre estime que le gradient $G = 0.2$ est trop permissif et propose de pass
|
||||
- **Transparence** : toute modification de regle est tracable et soumise au vote.
|
||||
- **Coherence** : les regles de modification sont les memes que les regles de decision (le systeme s'applique a lui-meme).
|
||||
|
||||
## Comprendre les resultats
|
||||
|
||||
La page de resultat affiche :
|
||||
|
||||
| Information | Description |
|
||||
| ------------------- | ---------------------------------------------------- |
|
||||
| Votes pour | Nombre de votes favorables |
|
||||
| Votes contre | Nombre de votes defavorables |
|
||||
| Total | Nombre total de votes exprimes |
|
||||
| Taille WoT | Nombre de membres WoT eligibles (snapshot au debut) |
|
||||
| Seuil requis | Seuil calcule par la formule d'inertie |
|
||||
| Critere Smith | Seuil et validation des votes Smith (si applicable) |
|
||||
| Critere TechComm | Seuil et validation des votes TechComm (si applicable) |
|
||||
| Resultat | **Adopte** ou **Rejete** |
|
||||
|
||||
### Exemple concret
|
||||
|
||||
Pour le vote de l'Engagement Forgeron v2.0.0 :
|
||||
|
||||
- Taille WoT : 7224 membres
|
||||
- 97 votes pour, 23 votes contre (120 total)
|
||||
- Seuil calcule : 94 (avec les parametres M50 B.1 G.2)
|
||||
- Resultat : **Adopte** (97 >= 94)
|
||||
|
||||
La faible participation (120 sur 7224 = 1.7%) a rendu le seuil exigeant (94 pour sur 120 = 78%), bien au-dessus de la majorite simple de 50%.
|
||||
|
||||
## Preuve cryptographique
|
||||
|
||||
Chaque vote est accompagne d'une signature Ed25519 qui garantit :
|
||||
@@ -296,3 +387,25 @@ Chaque session de vote est liee a un **protocole de vote** qui definit :
|
||||
- Les criteres Smith et TechComm eventuels
|
||||
|
||||
Les protocoles sont reutilisables et peuvent eux-memes etre soumis a meta-gouvernance.
|
||||
|
||||
## FAQ Vote
|
||||
|
||||
### Le seuil peut-il changer pendant le vote ?
|
||||
|
||||
Oui. Le seuil depend du nombre total de votes exprimes ($T$). A chaque nouveau vote, le seuil est recalcule. Il augmente legerement a mesure que la participation croit, mais converge vers la majorite simple. C'est pourquoi le resultat affiche est toujours provisoire tant que la session est ouverte.
|
||||
|
||||
### Que se passe-t-il si le seuil n'est pas atteint a la cloture ?
|
||||
|
||||
Le vote est **rejete**. La proposition n'est pas adoptee et le statu quo est maintenu. Le resultat detaille est archive dans le Sanctuaire pour transparence.
|
||||
|
||||
### Un vote en cours peut-il etre annule ?
|
||||
|
||||
Seul le createur de la session ou un membre du Comite Technique peut cloturer une session de maniere anticipee. La cloture anticipee calcule le resultat avec les votes exprimes a ce moment.
|
||||
|
||||
### Comment sont geres les ex aequo ?
|
||||
|
||||
Il n'y a pas d'ex aequo possible avec la formule d'inertie. Le seuil est un nombre entier (arrondi inferieur) et le nombre de votes favorables est un entier. Si `votes_pour >= seuil`, le vote est adopte. Sinon, il est rejete.
|
||||
|
||||
### Puis-je voter si mon statut WoT change pendant le vote ?
|
||||
|
||||
Votre statut WoT est enregistre au moment de votre vote. Si vous perdez votre statut de membre apres avoir vote, votre vote reste comptabilise car le snapshot de la taille WoT est pris au debut de la session.
|
||||
|
||||
@@ -5,21 +5,76 @@ description: Guide de l'archivage immuable sur Glibredecision
|
||||
|
||||
# Sanctuaire
|
||||
|
||||
## Principe
|
||||
## Qu'est-ce que le Sanctuaire ?
|
||||
|
||||
Le Sanctuaire est la couche d'archivage immuable de Glibredecision. Chaque document adopte, resultat de vote ou decision finalisee est archive de maniere permanente grace a trois mecanismes :
|
||||
Le Sanctuaire est la couche d'**archivage immuable** de Glibredecision. C'est l'endroit ou les decisions adoptees, les documents archives et les resultats de vote sont preserves de maniere permanente et verifiable.
|
||||
|
||||
1. **Hash SHA-256** du contenu pour garantir l'integrite
|
||||
2. **Stockage IPFS** pour la distribution decentralisee
|
||||
3. **Ancrage on-chain** via `system.remark` sur la blockchain Duniter V2
|
||||
Le principe est simple : une fois qu'un contenu entre dans le Sanctuaire, il ne peut plus etre modifie ni supprime. Meme si la plateforme Glibredecision disparaissait, les preuves resteraient accessibles et verifiables de maniere independante.
|
||||
|
||||
## Triple preuve : SHA-256 + IPFS + Blockchain
|
||||
|
||||
Le Sanctuaire repose sur trois mecanismes complementaires qui forment une **triple preuve** d'integrite :
|
||||
|
||||
### 1. Hash SHA-256 -- Preuve d'integrite
|
||||
|
||||
Un hash SHA-256 est un empreinte numerique unique du contenu. Si ne serait-ce qu'un seul caractere du document change, le hash est completement different. En recalculant le hash et en le comparant a celui enregistre, on peut verifier que le contenu n'a pas ete modifie.
|
||||
|
||||
**Analogie** : C'est comme une empreinte digitale. Deux documents differents n'auront jamais la meme empreinte.
|
||||
|
||||
### 2. IPFS -- Stockage distribue et contenu adressable
|
||||
|
||||
IPFS (InterPlanetary File System) est un reseau de stockage distribue. Le contenu n'est pas stocke sur un seul serveur mais replique sur plusieurs noeuds du reseau. Chaque contenu est identifie par un **CID** (Content Identifier) qui est derive de son contenu meme.
|
||||
|
||||
**Analogie** : Au lieu de dire "le document est a l'adresse www.example.com/doc1" (localisation), on dit "le document dont l'empreinte est Qm1234..." (contenu). Peu importe ou il est stocke, tant que l'empreinte correspond, c'est le bon document.
|
||||
|
||||
**Avantages** :
|
||||
|
||||
- **Resilience** : le contenu reste accessible meme si un serveur tombe.
|
||||
- **Integritegarantie** : le CID change si le contenu change, toute falsification est detectable.
|
||||
- **Perennite** : tant qu'au moins un noeud heberge le contenu, il est accessible.
|
||||
|
||||
### Acceder au contenu via IPFS
|
||||
|
||||
Chaque entree du Sanctuaire possede un **CID IPFS** qui permet d'acceder au contenu :
|
||||
|
||||
- **Passerelle publique** : `https://ipfs.io/ipfs/{CID}`
|
||||
- **Passerelle locale** (si vous executez un noeud kubo) : `http://localhost:8080/ipfs/{CID}`
|
||||
|
||||
En cliquant sur le lien CID dans l'interface, le contenu s'ouvre directement dans votre navigateur.
|
||||
|
||||
Si vous avez un noeud IPFS local (kubo), vous pouvez aussi utiliser la ligne de commande :
|
||||
|
||||
```bash
|
||||
# Afficher le contenu
|
||||
ipfs cat {CID}
|
||||
|
||||
# Telecharger le contenu
|
||||
ipfs get {CID} -o document_archive.txt
|
||||
```
|
||||
|
||||
### 3. Ancrage on-chain -- Preuve horodatee et infalsifiable
|
||||
|
||||
L'ancrage on-chain consiste a enregistrer le hash SHA-256 du contenu sur la blockchain Duniter V2, via un appel `system.remark`. Cette transaction est incluse dans un bloc de la blockchain, ce qui fournit :
|
||||
|
||||
- **Horodatage** : la date du bloc prouve que le contenu existait a cette date.
|
||||
- **Immutabilite** : une fois inscrit dans la blockchain, le remark ne peut pas etre modifie.
|
||||
- **Independance** : la preuve est verifiable sur la blockchain, independamment de Glibredecision.
|
||||
|
||||
Le format du remark est :
|
||||
|
||||
```
|
||||
glibredecision:sanctuary:{hash_sha256_du_contenu}
|
||||
```
|
||||
|
||||
**Analogie** : C'est comme publier un hash dans un journal date et immuable. N'importe qui peut verifier que le hash etait bien la a cette date.
|
||||
|
||||
## Pourquoi le Sanctuaire ?
|
||||
|
||||
La gouvernance exige la transparence et la tracabilite. Le Sanctuaire garantit que :
|
||||
|
||||
- Aucune decision adoptee ne peut etre modifiee retroactivement
|
||||
- Tout membre peut verifier l'authenticite d'un document ou d'un resultat de vote
|
||||
- L'historique des decisions est preservee independamment de la plateforme
|
||||
- **Aucune decision adoptee ne peut etre modifiee retroactivement** : le hash et l'ancrage on-chain rendent toute falsification detectable.
|
||||
- **Tout membre peut verifier l'authenticite** d'un document ou d'un resultat de vote de maniere independante.
|
||||
- **L'historique des decisions est preserve** independamment de la plateforme : meme sans Glibredecision, les preuves restent sur IPFS et la blockchain.
|
||||
|
||||
## Types d'entrees
|
||||
|
||||
@@ -51,7 +106,7 @@ Pour retrouver toutes les entrees du Sanctuaire liees a un document, une decisio
|
||||
|
||||
Cette fonctionnalite permet de retracer l'historique complet d'archivage d'un document au fil de ses modifications adoptees.
|
||||
|
||||
## Verification d'integrite
|
||||
## Comment verifier une archive
|
||||
|
||||
### Verification automatique
|
||||
|
||||
@@ -69,44 +124,46 @@ Glibredecision propose une verification automatique d'integrite pour chaque entr
|
||||
Si les trois controles sont valides, le contenu est authentique et n'a pas ete modifie depuis son archivage.
|
||||
::
|
||||
|
||||
### Verification manuelle
|
||||
### Verification manuelle (independante de la plateforme)
|
||||
|
||||
Pour une verification independante de la plateforme :
|
||||
Pour une verification totalement independante de Glibredecision, suivez ces etapes :
|
||||
|
||||
1. Recuperez le contenu via IPFS en utilisant le CID affiche.
|
||||
2. Calculez le hash SHA-256 du contenu telecharge.
|
||||
3. Comparez avec le hash enregistre dans le Sanctuaire.
|
||||
4. Verifiez que le meme hash est present dans le remark on-chain (via un explorateur blockchain).
|
||||
#### Etape 1 : Recuperer le contenu via IPFS
|
||||
|
||||
Si les trois hash correspondent, le contenu est authentique et n'a pas ete modifie.
|
||||
|
||||
## Acces au contenu via IPFS
|
||||
|
||||
Chaque entree du Sanctuaire possede un **CID IPFS** (Content Identifier) qui permet d'acceder au contenu archive de maniere decentralisee.
|
||||
|
||||
### Utiliser le lien IPFS gateway
|
||||
|
||||
Le CID est affiche sous forme de lien cliquable pointant vers une passerelle IPFS publique :
|
||||
|
||||
- **Passerelle publique** : `https://ipfs.io/ipfs/{CID}`
|
||||
- **Passerelle locale** (si vous executez un noeud kubo) : `http://localhost:8080/ipfs/{CID}`
|
||||
|
||||
En cliquant sur le lien CID dans l'interface, le contenu archive s'ouvre directement dans votre navigateur.
|
||||
|
||||
### Recuperer le contenu via la CLI IPFS
|
||||
|
||||
Si vous avez un noeud IPFS local (kubo), vous pouvez recuperer le contenu directement :
|
||||
Utilisez le CID affiche sur l'entree du Sanctuaire pour telecharger le contenu :
|
||||
|
||||
```bash
|
||||
ipfs cat {CID}
|
||||
# Via un noeud IPFS local
|
||||
ipfs cat QmXyz... > document.txt
|
||||
|
||||
# Via une passerelle publique
|
||||
curl https://ipfs.io/ipfs/QmXyz... > document.txt
|
||||
```
|
||||
|
||||
Ou le telecharger :
|
||||
#### Etape 2 : Calculer le hash SHA-256
|
||||
|
||||
```bash
|
||||
ipfs get {CID} -o document_archive.txt
|
||||
sha256sum document.txt
|
||||
```
|
||||
|
||||
Comparez le hash obtenu avec le hash affiche dans le Sanctuaire. Ils doivent etre identiques.
|
||||
|
||||
#### Etape 3 : Verifier l'ancrage on-chain
|
||||
|
||||
1. Copiez le **hash de transaction** affiche sur l'entree du Sanctuaire.
|
||||
2. Ouvrez un explorateur de la blockchain Duniter V2 (par exemple Polkadot.js Apps connecte au reseau Duniter).
|
||||
3. Recherchez la transaction par son hash ou parcourez le **bloc** indique.
|
||||
4. Dans les extrinsics du bloc, reperez l'appel `system.remark` contenant le hash SHA-256.
|
||||
5. Verifiez que le hash dans le remark correspond a celui que vous avez calcule.
|
||||
|
||||
#### Resultat
|
||||
|
||||
Si les trois hash correspondent (calcul local, Sanctuaire, on-chain), le contenu est authentique, integre et horodate. La triple preuve est confirmee.
|
||||
|
||||
::callout{type="tip"}
|
||||
L'ancrage on-chain fournit une preuve horodatee et infalsifiable de l'existence du contenu a la date du bloc. Meme si la plateforme Glibredecision disparait, la preuve reste verifiable sur la blockchain.
|
||||
::
|
||||
|
||||
## Comprendre les informations d'ancrage on-chain
|
||||
|
||||
Chaque entree du Sanctuaire affiche des informations relatives a son ancrage sur la blockchain Duniter V2 :
|
||||
@@ -117,20 +174,6 @@ Chaque entree du Sanctuaire affiche des informations relatives a son ancrage sur
|
||||
| Numero de bloc | Le bloc de la blockchain dans lequel la transaction a ete incluse |
|
||||
| Date d'archivage | Horodatage de la creation de l'entree dans le Sanctuaire |
|
||||
|
||||
### Verifier sur un explorateur blockchain
|
||||
|
||||
Pour verifier l'ancrage on-chain de maniere independante :
|
||||
|
||||
1. Copiez le **hash de transaction** affiche sur l'entree du Sanctuaire.
|
||||
2. Ouvrez un explorateur de la blockchain Duniter V2 (par exemple Polkadot.js Apps connecte au reseau Duniter).
|
||||
3. Recherchez la transaction par son hash ou parcourez le **bloc** indique.
|
||||
4. Dans les extrinsics du bloc, reperer l'appel `system.remark` contenant le hash SHA-256 du contenu.
|
||||
5. Si le hash dans le remark correspond au hash SHA-256 affiche dans le Sanctuaire, l'ancrage est confirme.
|
||||
|
||||
::callout{type="tip"}
|
||||
L'ancrage on-chain fournit une preuve horodatee et infalsifiable de l'existence du contenu a la date du bloc. Meme si la plateforme Glibredecision disparait, la preuve reste verifiable sur la blockchain.
|
||||
::
|
||||
|
||||
## Automatisation
|
||||
|
||||
L'archivage dans le Sanctuaire est declenche automatiquement lorsqu'un processus decisionnel est finalise :
|
||||
@@ -139,3 +182,23 @@ L'archivage dans le Sanctuaire est declenche automatiquement lorsqu'un processus
|
||||
- Quand une session de vote est **cloturee**, le resultat detaille est archive.
|
||||
- Quand une decision est **executee**, l'ensemble de la decision est archive.
|
||||
- Quand un document est **archive** via le bouton d'archivage, l'integralite du document est archivee dans le Sanctuaire.
|
||||
|
||||
## Resume : la chaine de confiance
|
||||
|
||||
```
|
||||
Contenu adopte
|
||||
|
|
||||
v
|
||||
[Calcul SHA-256] --> hash = empreinte unique du contenu
|
||||
|
|
||||
+---> [Upload IPFS] --> CID = identifiant distribue du contenu
|
||||
|
|
||||
+---> [system.remark on-chain] --> preuve horodatee et immuable
|
||||
|
|
||||
v
|
||||
[Entree Sanctuaire] = hash + CID + tx_hash + block_number
|
||||
|
|
||||
v
|
||||
Verification : recalculer le hash, comparer avec IPFS et on-chain
|
||||
= Triple preuve d'integrite
|
||||
```
|
||||
|
||||
@@ -13,33 +13,99 @@ Pour **consulter** les documents, decisions et resultats de vote, aucune authent
|
||||
|
||||
### Comment fonctionne la connexion sans mot de passe ?
|
||||
|
||||
Glibredecision utilise un systeme challenge-response base sur la cryptographie Ed25519. Vous signez un texte aleatoire avec votre cle privee, et la plateforme verifie la signature avec votre cle publique. Votre cle privee n'est jamais transmise.
|
||||
Glibredecision utilise un systeme challenge-response base sur la cryptographie Ed25519. Voici le processus :
|
||||
|
||||
1. Vous fournissez votre adresse Duniter SS58.
|
||||
2. Le serveur genere un texte aleatoire (le "challenge") de 64 caracteres hexadecimaux.
|
||||
3. Votre extension Polkadot.js ou votre portefeuille Cesium signe ce challenge avec votre cle privee Ed25519.
|
||||
4. Le serveur verifie la signature avec votre cle publique.
|
||||
5. Si la verification reussit, un jeton de session vous est attribue.
|
||||
|
||||
Votre cle privee n'est **jamais** transmise au serveur. Seule la signature du challenge est envoyee.
|
||||
|
||||
### Quels portefeuilles sont compatibles ?
|
||||
|
||||
Tout portefeuille supportant la signature Ed25519 sur Substrate est compatible :
|
||||
|
||||
- **Extension Polkadot.js** (recommandee) : disponible sur Chrome et Firefox
|
||||
- **Cesium2** : l'application officielle de la communaute Duniter
|
||||
- **Tout portefeuille Substrate** supportant Ed25519
|
||||
|
||||
### Ma session a expire, que faire ?
|
||||
|
||||
Les sessions durent 24 heures. Reconnectez-vous en suivant le meme processus (challenge + signature). Vos votes et propositions precedents ne sont pas affectes.
|
||||
|
||||
### Que se passe-t-il si je perds l'acces a ma cle privee ?
|
||||
|
||||
Glibredecision ne stocke jamais votre cle privee. Si vous perdez l'acces a votre cle, vous ne pourrez plus vous authentifier avec cette adresse. Vos votes passes restent enregistres et comptabilises. Contactez la communaute Duniter pour les procedures de recuperation d'identite si necessaire.
|
||||
|
||||
### Puis-je me connecter depuis plusieurs appareils ?
|
||||
|
||||
Oui. Chaque connexion genere un jeton de session independant. Vous pouvez etre connecte simultanement depuis plusieurs appareils. Chaque session est independante et expire apres 24 heures.
|
||||
|
||||
## Vote
|
||||
|
||||
### Comment voter sur un item de document ?
|
||||
|
||||
1. Rendez-vous dans la section **Votes** ou accedez a une decision en cours.
|
||||
2. Lisez le sujet soumis au vote.
|
||||
3. Choisissez **Pour** ou **Contre** (vote binaire) ou un niveau de 0 a 5 (vote nuance).
|
||||
4. Optionnellement, ajoutez un commentaire.
|
||||
5. Signez le payload avec votre cle privee (votre extension de portefeuille vous le demandera).
|
||||
6. Cliquez sur **Soumettre**.
|
||||
|
||||
### Puis-je changer mon vote ?
|
||||
|
||||
Oui, tant que la session de vote est ouverte, vous pouvez modifier votre vote autant de fois que necessaire. L'ancien vote est conserve en base de donnees pour l'audit mais marque comme inactif. Seul le dernier vote est pris en compte dans le decompte.
|
||||
|
||||
### Pourquoi le seuil est-il si eleve quand peu de personnes votent ?
|
||||
|
||||
C'est le mecanisme d'**inertie**. Quand la participation est faible, le seuil est eleve pour empecher qu'un petit groupe prenne des decisions engageant toute la communaute. A mesure que la participation augmente, le seuil converge vers la majorite simple. Cela incite a la participation large.
|
||||
|
||||
### Puis-je changer mon vote ?
|
||||
Par exemple, avec 120 votes sur une WoT de 7224 membres (1.7% de participation), il faut 78% de votes favorables. Si toute la WoT votait, 50% suffiraient.
|
||||
|
||||
Oui, tant que la session de vote est ouverte, vous pouvez modifier votre vote. L'ancien vote est conserve en base de donnees pour l'audit mais marque comme inactif. Seul le dernier vote est pris en compte dans le decompte.
|
||||
### Comment comprendre le seuil affiche sur la jauge ?
|
||||
|
||||
La jauge de seuil montre :
|
||||
|
||||
- **La barre verte** : nombre de votes favorables actuels
|
||||
- **La barre rouge** : nombre de votes defavorables
|
||||
- **Le trait vertical** : position du seuil requis (calcule par la formule d'inertie)
|
||||
- **Le compteur** : `votes_pour / seuil` (par exemple "97 / 94")
|
||||
- **Le badge** : "Adopte" si votes_pour >= seuil, sinon "Non atteint"
|
||||
|
||||
Le seuil est recalcule en temps reel a chaque nouveau vote.
|
||||
|
||||
### Qu'est-ce que le critere Smith ?
|
||||
|
||||
Certaines decisions exigent un nombre minimum de votes favorables de la part des **forgerons** (membres Smith de la WoT). Cela garantit que les decisions techniques sont soutenues par ceux qui maintiennent le reseau.
|
||||
Certaines decisions exigent un nombre minimum de votes favorables de la part des **forgerons** (membres Smith de la WoT). Le seuil est calcule par `ceil(SmithWotSize^S)` ou S est l'exposant configure. Cela garantit que les decisions techniques sont soutenues par ceux qui maintiennent le reseau.
|
||||
|
||||
### Qu'est-ce que le critere TechComm ?
|
||||
|
||||
De maniere similaire, certaines decisions exigent un nombre minimum de votes favorables du **Comite Technique**. Cela concerne les decisions qui affectent le runtime ou l'infrastructure technique.
|
||||
De maniere similaire, certaines decisions exigent un nombre minimum de votes favorables du **Comite Technique**. Le seuil est calcule par `ceil(CoTecSize^T)`. Cela concerne les decisions qui affectent le runtime ou l'infrastructure technique.
|
||||
|
||||
### Comment fonctionnent les votes nuances ?
|
||||
|
||||
Au lieu de "pour" ou "contre", vous choisissez un niveau de 0 (CONTRE) a 5 (TOUT A FAIT). Les niveaux 3, 4 et 5 comptent comme positifs. Pour que le vote soit adopte, il faut que les votes positifs representent au moins 80% du total et qu'un nombre minimum de participants soit atteint.
|
||||
Au lieu de "pour" ou "contre", vous choisissez un niveau de 0 (CONTRE) a 5 (TOUT A FAIT). Les niveaux 3, 4 et 5 comptent comme positifs. Pour que le vote soit adopte, il faut que les votes positifs representent au moins 80% du total et qu'un nombre minimum de participants soit atteint (par defaut 59).
|
||||
|
||||
### Que signifie "D30M50B.1G.2S.1T.1" ?
|
||||
|
||||
C'est le codage compact des parametres de formule :
|
||||
|
||||
- **D30** : duree de 30 jours
|
||||
- **M50** : majorite cible de 50%
|
||||
- **B.1** : exposant de base 0.1
|
||||
- **G.2** : gradient 0.2
|
||||
- **S.1** : critere Smith avec exposant 0.1
|
||||
- **T.1** : critere TechComm avec exposant 0.1
|
||||
|
||||
### Les votes sont-ils secrets ?
|
||||
|
||||
Non. Les votes et leurs signatures cryptographiques sont **publics**, conformement au principe de transparence de la gouvernance. Chaque vote peut etre verifie independamment par quiconque possede la cle publique du votant. Il n'y a pas de vote secret dans Glibredecision.
|
||||
|
||||
### Le seuil peut-il changer pendant le vote ?
|
||||
|
||||
Oui. Le seuil depend du nombre total de votes exprimes. A chaque nouveau vote, le seuil est recalcule. Il augmente legerement a mesure que la participation croit, mais converge vers la majorite simple. C'est pourquoi le resultat affiche est toujours provisoire tant que la session est ouverte.
|
||||
|
||||
## Documents
|
||||
|
||||
@@ -47,34 +113,146 @@ Au lieu de "pour" ou "contre", vous choisissez un niveau de 0 (CONTRE) a 5 (TOUT
|
||||
|
||||
Un document de reference est un texte fondateur de la communaute Duniter (Licence G1, Engagement Forgeron, Reglement du Comite Technique, etc.). Il est compose d'items modulaires sous vote permanent.
|
||||
|
||||
### Qu'est-ce qu'un item ?
|
||||
|
||||
Un item est une unite modulaire d'un document : une clause, une regle, une verification, un preambule ou une section. Chaque item a une position hierarchique (ex: "1", "1.1", "3.2"), un texte courant et un historique de versions.
|
||||
|
||||
### Comment proposer une modification ?
|
||||
|
||||
Ouvrez le document, selectionnez l'item a modifier, cliquez sur "Proposer une modification", redigez le nouveau texte avec une justification, puis soumettez. La proposition sera soumise a un processus de decision et de vote.
|
||||
1. Ouvrez le document dans la section **Documents**.
|
||||
2. Selectionnez l'item a modifier.
|
||||
3. Cliquez sur **Proposer une modification**.
|
||||
4. Redigez le nouveau texte avec une justification.
|
||||
5. Soumettez.
|
||||
|
||||
Un diff automatique est genere. La proposition sera soumise a examen et vote par la communaute.
|
||||
|
||||
### Que signifie "vote permanent" ?
|
||||
|
||||
Les documents actifs sont toujours ouverts aux propositions de modification. Il n'y a pas de periode speciale pour proposer des changements. Cela permet une evolution continue et organique des textes.
|
||||
|
||||
## Sanctuaire
|
||||
### Puis-je proposer plusieurs modifications a la fois ?
|
||||
|
||||
Oui. Vous pouvez proposer des modifications a differents items d'un meme document, ou a des items de documents differents. Chaque proposition est independante et suit son propre cycle de vie (proposition, examen, vote).
|
||||
|
||||
### Que se passe-t-il si ma proposition est rejetee ?
|
||||
|
||||
Le texte courant de l'item reste inchange. Votre proposition est archivee avec le statut "rejetee" pour transparence. Vous pouvez proposer une nouvelle modification a tout moment, eventuellement amelioree suite aux retours de la communaute.
|
||||
|
||||
### Comment consulter le diff d'une proposition ?
|
||||
|
||||
Sur la page de detail d'une version proposee, le diff est affiche automatiquement. Les ajouts sont surlignees en vert, les suppressions en rouge. Vous pouvez basculer entre la vue diff et la vue texte complet.
|
||||
|
||||
## Decisions et mandats
|
||||
|
||||
### Quelle est la difference entre un document et une decision ?
|
||||
|
||||
Un **document** est un texte fondateur sous vote permanent (Licence, Engagement, Reglement). Une **decision** est un processus ponctuel multi-etapes (qualification, examen, vote, execution, rapport) pour prendre un choix collectif specifique (runtime upgrade, attribution de mandat, changement de parametre).
|
||||
|
||||
### Comment creer une decision ?
|
||||
|
||||
1. Rendez-vous dans la section **Decisions**.
|
||||
2. Cliquez sur **Nouvelle decision**.
|
||||
3. Renseignez le titre, la description, le contexte et le type.
|
||||
4. Choisissez un protocole de vote.
|
||||
5. Ajoutez les etapes necessaires (qualification, examen, vote, execution, reporting).
|
||||
6. Soumettez, puis utilisez **Avancer** pour demarrer le processus.
|
||||
|
||||
### Qu'est-ce qu'un mandat ?
|
||||
|
||||
Un mandat est une responsabilite formelle attribuee a un membre de la communaute pour une duree determinee, apres validation par vote collectif. Les types de mandats sont : `techcomm` (Comite Technique), `smith` (forgeron) et `custom` (personnalise).
|
||||
|
||||
### Comment fonctionne l'election d'un mandataire ?
|
||||
|
||||
Le processus suit un cycle : formulation du mandat, periode de candidature, vote collectif, assignation du mandataire, exercice du mandat, reporting et completion. Le vote utilise le meme systeme de seuil WoT avec inertie.
|
||||
|
||||
### Un mandat peut-il etre revoque ?
|
||||
|
||||
Oui. Un mandat actif peut etre revoque de maniere anticipee via l'action "Revoquer". La revocation est une action de gouvernance qui peut necessiter un vote prealable.
|
||||
|
||||
## Sanctuaire et archivage
|
||||
|
||||
### Pourquoi archiver sur IPFS et la blockchain ?
|
||||
|
||||
IPFS fournit un stockage distribue : le contenu est accessible meme si la plateforme Glibredecision est hors ligne. L'ancrage on-chain via `system.remark` cree une preuve horodatee immuable sur la blockchain Duniter. Ensemble, ils garantissent que les decisions de la communaute sont preservees de maniere permanente et verifiable.
|
||||
**IPFS** fournit un stockage distribue : le contenu est accessible meme si la plateforme Glibredecision est hors ligne. L'**ancrage on-chain** via `system.remark` cree une preuve horodatee immuable sur la blockchain Duniter V2. Le **hash SHA-256** garantit l'integrite du contenu. Ensemble, ils forment une **triple preuve** que le contenu n'a pas ete modifie depuis son archivage.
|
||||
|
||||
### Comment verifier qu'un document n'a pas ete modifie ?
|
||||
|
||||
Telechargez le document depuis IPFS via son CID, calculez le hash SHA-256, puis comparez-le au hash enregistre dans le Sanctuaire et au remark on-chain. Si les trois correspondent, le document est intact.
|
||||
Trois methodes :
|
||||
|
||||
## Technique
|
||||
1. **Verification automatique** : cliquez sur **Verifier l'integrite** sur l'entree du Sanctuaire. Le systeme recalcule le hash et verifie IPFS et on-chain automatiquement.
|
||||
2. **Verification manuelle** : telechargez le contenu depuis IPFS via son CID, calculez le hash SHA-256 avec `sha256sum`, puis comparez avec le hash enregistre dans le Sanctuaire et le remark on-chain.
|
||||
3. **Verification blockchain** : consultez le bloc reference dans un explorateur Duniter V2 et verifiez le `system.remark`.
|
||||
|
||||
### L'archivage est-il automatique ?
|
||||
|
||||
Oui. L'archivage est declenche automatiquement :
|
||||
|
||||
- Quand une version d'item de document est acceptee
|
||||
- Quand une session de vote est cloturee
|
||||
- Quand une decision est executee
|
||||
- Quand un document est archive manuellement
|
||||
|
||||
### Puis-je acceder aux archives sans Glibredecision ?
|
||||
|
||||
Oui. Les contenus archives sont accessibles via :
|
||||
|
||||
- **IPFS** : utilisez le CID pour recuperer le contenu depuis n'importe quelle passerelle IPFS publique ou un noeud local
|
||||
- **Blockchain** : le hash SHA-256 est enregistre dans un `system.remark` sur la blockchain Duniter V2, verifiable via tout explorateur compatible
|
||||
|
||||
## Questions techniques
|
||||
|
||||
### Sur quelle blockchain Glibredecision fonctionne-t-il ?
|
||||
|
||||
Glibredecision se connecte a la blockchain **Duniter V2** (basee sur Substrate). En environnement de developpement, il se connecte au reseau de test GDev (`wss://gdev.p2p.legal/ws`).
|
||||
|
||||
### Que se passe-t-il si la blockchain Duniter est indisponible ?
|
||||
|
||||
L'essentiel des fonctionnalites (consultation des documents, votes, decisions) reste accessible car les donnees sont stockees dans la base PostgreSQL locale. Seules les fonctions dependant de la blockchain sont affectees :
|
||||
|
||||
- L'authentification peut temporairement echouer si la verification WoT n'est pas en cache
|
||||
- L'ancrage on-chain des entrees du Sanctuaire est differe jusqu'au retablissement
|
||||
- Les snapshots de taille WoT/Smith/TechComm utilisent le cache
|
||||
|
||||
### Que se passe-t-il si le noeud IPFS est indisponible ?
|
||||
|
||||
L'upload sur IPFS est differe si le noeud est temporairement indisponible. Le hash SHA-256 et les metadonnees sont enregistres dans la base de donnees. L'upload peut etre relance ulterieurement. Le contenu deja uploade reste accessible via les passerelles IPFS publiques.
|
||||
|
||||
### Les donnees de vote sont-elles publiques ?
|
||||
|
||||
Oui. Les votes et leurs signatures cryptographiques sont publics, conformement au principe de transparence de la gouvernance. Chaque vote peut etre verifie independamment.
|
||||
|
||||
### Les mises a jour sont-elles en temps reel ?
|
||||
|
||||
Oui. Glibredecision utilise une connexion WebSocket pour diffuser les mises a jour en temps reel :
|
||||
|
||||
- Nouveaux votes soumis : la jauge de seuil est recalculee instantanement
|
||||
- Votes modifies : la jauge reflette le changement immediatement
|
||||
- Sessions cloturees : le resultat final s'affiche
|
||||
- Un indicateur de connexion (point vert/orange/rouge) en bas a droite indique l'etat de la connexion temps reel
|
||||
|
||||
### Ou est heberge Glibredecision ?
|
||||
|
||||
La plateforme est hebergee sur une infrastructure geree par la communaute, avec deploiement automatise via Docker et Woodpecker CI. Le code source est ouvert et disponible sur le depot Git Duniter.
|
||||
|
||||
## Securite
|
||||
|
||||
### Ma cle privee est-elle transmise au serveur ?
|
||||
|
||||
Non. Jamais. L'authentification utilise un mecanisme challenge-response : vous signez un texte aleatoire avec votre cle privee, et seule la signature est envoyee au serveur. La cle privee reste exclusivement dans votre portefeuille (extension Polkadot.js, Cesium, etc.).
|
||||
|
||||
### Comment la signature Ed25519 protege-t-elle mon vote ?
|
||||
|
||||
Chaque vote est accompagne d'une signature Ed25519 qui garantit :
|
||||
|
||||
- **Authenticite** : seul le proprietaire de l'adresse Duniter peut voter en son nom
|
||||
- **Integrite** : le payload signe contient le vote, l'identifiant de la session et un horodatage. Toute modification du vote apres signature est detectable.
|
||||
- **Non-repudiation** : le votant ne peut pas nier avoir vote
|
||||
|
||||
### Mes votes peuvent-ils etre falsifies ?
|
||||
|
||||
Non. Chaque vote est signe cryptographiquement avec votre cle privee Ed25519. Le payload signe contient le vote, l'identifiant de la session et un horodatage. Toute modification du vote apres signature est detectable car la verification de la signature echouerait. De plus, les votes sont publics et verifiables par n'importe qui.
|
||||
|
||||
### Comment verifier la signature d'un vote ?
|
||||
|
||||
Sur la page d'une session de vote, chaque vote affiche un lien **Verifier la signature**. En cliquant, le systeme utilise la cle publique du votant (derivee de son adresse SS58) pour verifier que la signature correspond bien au payload affiche. Vous pouvez aussi effectuer cette verification de maniere independante avec n'importe quelle bibliotheque Ed25519.
|
||||
|
||||
Reference in New Issue
Block a user